<?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 xml:lang="en" id="GUID-1A5C7320-B017-5CD9-B3EA-1301CC08A762"><title>User Prompt Service Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>User Prompt Service (UPS) allows device creators to specify whether requests made by applications to access services, such as a request to make a telephone call, are processed silently or whether they require the user to be prompted. </p> <section><title>Purpose</title> <p>An application requests a service. The service provider (a system server) requests a decision from the UPS. The UPS searches for a matching policy file and policy. Based on the policy for the service, the service request may be immediately accepted or denied or it may need to receive a decision from the user, in which case it is accepted or denied after several further steps are carried out. </p> <p>Device creators can customize the circumstances under which prompts are generated by configuring policies. Policies are made up of details about the service being requested as well as information about whether to accept or deny silently or to ask the user. They are defined in policy lists. Each service has one policy list defining any number of policies. In cases where the policy specifies that a user prompt is required, ECom plug-ins called <xref href="GUID-43080A86-72D3-5422-953E-A5EF79961D7B.dita">Policy Evaluators</xref> and <xref href="GUID-A8130D83-E684-5B6C-BDFE-EB6EE3CD49E8.dita">Dialog Creators</xref>, written by device creators. </p> </section> <section><title>Key concepts</title> <p>The component has the following key concepts: </p> <dl><dlentry><dt>Policy</dt> <dd><p>Policies specify whether application requests to access services should be processed silently or whether the user should be prompted for a decision. Policies may be general or specific – for example a policy may be specific to a single application, a group of applications or a class of applications (For example, those with unprotected secure ids). Policies are defined in policy lists. Device creators define policies. </p> </dd> </dlentry> <dlentry><dt>UPS policy file</dt> <dd><p>A UPS policy file is a compiled resource file containing all of the policies for a given service. The policies are ordered from most specific to least specific. </p> <p>Because policies are matched in order, each service may have only one policy file. To define a policy safely, you need to know which other policies have been defined. If you place a general policy near the beginning of the list of policies, you prevent other policies from being evaluated. </p> </dd> </dlentry> <dlentry><dt>Policy evaluator</dt> <dd><p>Policy evaluators are Ecom plug-ins, which are responsible for generating fingerprints (see below) used to locate previous decision records related to the request. Device creators define policy evaluators. </p> </dd> </dlentry> <dlentry><dt>Dialog creator</dt> <dd><p>Dialog creators are Ecom plug-ins, which display and generate dialog prompts. Device creators define dialog creators. </p> </dd> </dlentry> <dlentry><dt>Fingerprint</dt> <dd><p>A fingerprint is a collection of data to do with the service being requested. The fingerprint usually includes the destination string supplied by the service that is matched to the destination string of a policy in the policy file. It might be a phone number, domain name, access point etc. A fingerprint is used to search the decision database for a match and to add a record to the decision database if a match was not found in the initial search. Device creators define the <codeph>GenerateFingerprints()</codeph> function in the Policy Evaluator plug-in. </p> <p>A fingerprint serves two purposes: </p> <ul><li id="GUID-2F6022DE-F9C0-5560-A966-F77F5F8077AC"><p>The UPS uses it to search the decision database for a match. </p> </li> <li id="GUID-2BB4C56D-055D-5E79-97D7-CCC2E0D69700"><p>If the UPS finds no record of a previous user decision and the user selects "always" or "never" in response to the UPS prompt, it uses the fingerprint to create a new record in the decision database. </p> </li> </ul> <p>It is possible to specify one or many policy evaluators. It is also possible not to specify a policy evaluator and to depend on the default policy evaluator. </p> </dd> </dlentry> <dlentry><dt>Decision database</dt> <dd><p>A decision database stores the phone user's choice of whether a request is always granted or never granted. Decisions stored in the decision database persist across reboots of the device. The decision database is provided by Symbian. </p> <p>The decision database may not be accessed directly. However, records may be retrieved and deleted via the management APIs. This might be used by a control-panel application. </p> </dd> </dlentry> </dl> </section> <section><title>Architectural relationships</title> <p>The UPS provides <xref href="GUID-F1FE58C4-2703-3651-8721-D018865BA169.dita"><apiname>CDialogCreator</apiname></xref> and <xref href="GUID-FDE91CAC-1588-3EED-B509-08168F4B881B.dita"><apiname>CPolicyEvaluator</apiname></xref> interfaces for device creators to implement. </p> <fig id="GUID-66482906-10D7-5536-87CE-0B97C1DFBB16"><title>
             UPS components 
          </title> <image href="GUID-9C837724-B00E-58F4-8B71-53ECDBFF5CCE_d0e376410_href.png" placement="inline"/></fig> </section> <section><title>API summary</title> <p>The following diagram shows the relationships between some of the key classes in the UPS. </p> <fig id="GUID-2D2DB4F6-6526-585A-835F-FD78E43B5079"><title>
             Class diagram of key classes in UPS 
          </title> <image href="GUID-395C240D-6487-5832-B5F6-FC92991001FE_d0e376424_href.png" placement="inline"/></fig> <table id="GUID-3A54E48E-35CF-5B20-8139-BF63B7EF3EDB"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><thead><row><entry>Class Name</entry> <entry>Description</entry> </row> </thead> <tbody><row><entry><p> <xref href="GUID-0A4AFA03-0424-3384-AFEC-083B31C86B5D.dita#GUID-0A4AFA03-0424-3384-AFEC-083B31C86B5D/GUID-179AD3F9-8121-3F65-B393-CA3924A3111B"><apiname>UserPromptService::CClientEntity</apiname></xref>  </p> </entry> <entry><p>Class representing an entity executing within a client process. For example, a script. </p> </entry> </row> <row><entry><p> <xref href="GUID-0A4AFA03-0424-3384-AFEC-083B31C86B5D.dita#GUID-0A4AFA03-0424-3384-AFEC-083B31C86B5D/GUID-0F7D8FF7-6176-32F8-8469-253D81848090"><apiname>UserPromptService::CDialogCreator</apiname></xref>  </p> </entry> <entry><p>Abstract base class for dialog creator Ecom plug-ins. Dialog creators are responsible for generating and displaying prompt dialogs. </p> </entry> </row> <row><entry><p> <xref href="GUID-0A4AFA03-0424-3384-AFEC-083B31C86B5D.dita#GUID-0A4AFA03-0424-3384-AFEC-083B31C86B5D/GUID-2E49A95A-8CAC-36B9-BAC8-A9DED4AE7CFE"><apiname>UserPromptService::CFingerprint</apiname></xref>  </p> </entry> <entry><p>Class that represents the fingerprint data for a stored decision. </p> </entry> </row> <row><entry><p> <xref href="GUID-0A4AFA03-0424-3384-AFEC-083B31C86B5D.dita#GUID-0A4AFA03-0424-3384-AFEC-083B31C86B5D/GUID-490A81F4-B763-3D01-AAAC-61B94793B0CB"><apiname>UserPromptService::CPolicy</apiname></xref>  </p> </entry> <entry><p>Class for a single policy record. </p> </entry> </row> <row><entry><p> <xref href="GUID-0A4AFA03-0424-3384-AFEC-083B31C86B5D.dita#GUID-0A4AFA03-0424-3384-AFEC-083B31C86B5D/GUID-65A2A57C-E9BB-3957-BC16-5579BF105329"><apiname>UserPromptService::CPolicyEvaluator</apiname></xref>  </p> </entry> <entry><p>Abstract base class for a policy evaluator Ecom plug-in. Policy evaluators are primarily responsible for generating the fingerprints used to locate previous decision records related to the current request. </p> </entry> </row> </tbody> </tgroup> </table> </section> <section><title>Typical uses</title> <p>The following diagram shows the sequence of activities performed by the UPS after it receives a request from a server: </p> <fig id="GUID-4FE4A657-5299-5D20-8E23-90C3EEC67462"><title>
             Diagram showing activities for a single request 
          </title> <image href="GUID-B7542EA6-6188-5A3D-A287-0766F7B42DC0_d0e376536_href.png" placement="inline"/></fig> <p>As is shown in the above diagram, the UPS returns a decision to the system server as in the following use cases: </p> <ul><li id="GUID-E414AB08-85A4-5686-88F1-584E17244DA9"><p>processing silently </p> </li> <li id="GUID-DFC214C2-D97C-550D-80EE-62653BDD9FFB"><p>finding a stored decision in the decision database </p> </li> <li id="GUID-266A70E9-67C4-5FA5-9E02-CB4ECC6E53E2"><p>prompting the user in a dialog and resulting in a "one-shot" or "session" (non-persistent) decision by the user </p> </li> <li id="GUID-25813297-93CD-5668-9DB2-1A0C7DC06A26"><p>prompting the user in a dialog and resulting in an "always" or "never" (persistent) decision by the user </p> </li> </ul> <p>The Policy Evaluator allows device creators to customize the behaviour of the UPS at run-time. Policy Evaluators may: </p> <ul><li id="GUID-281ACA0D-0927-5D0B-9F09-71256343ACC8"><p>Allow security decisions to be specific to the data on which the service acts instead of simply granting full access to the service, for example "Allow application X to send SMS messages to 01234567". This is supported via the fingerprint functionality. </p> </li> <li id="GUID-027E0704-7766-5742-AB35-3B49D9DEBEC6"><p>Allow a security decision to be specific to an individual script executing within a scripting host. This is supported via the client entity field. </p> </li> <li id="GUID-B20E7021-251F-59BD-ADBC-02EFEA09F5F2"><p>Allow a prompt to be displayed even if the user selected "Always" or "Never". This could be based on a usage threshold or simply as additional confirmation if the user selected "Never". This is supported via the force prompt functionality. </p> </li> </ul> </section> <section><title>Typical uses</title> <p>The UPS component provides interfaces to perform the following tasks: </p> <ul><li id="GUID-7D89C9F6-82E6-5B5C-9652-C8749E2BF759"><p><xref href="GUID-85D9878E-4FEF-5E45-9F87-53634CD171E0.dita">Integrating a System Server with UPS</xref>  </p> </li> <li id="GUID-B2633E58-3B5C-5763-A4AC-1BA0B624DAE3"><p><xref href="GUID-DB827750-6057-537E-8FE1-8F68BF2E9F99.dita">Writing a UPS Policy File</xref>  </p> </li> <li id="GUID-CDDBA2CE-A80B-5B7C-8865-D059052BD33C"><p><xref href="GUID-43080A86-72D3-5422-953E-A5EF79961D7B.dita">Writing a UPS Policy Evaluator</xref>  </p> </li> <li id="GUID-69F5480D-3575-5124-AE14-F458FC03A578"><p><xref href="GUID-A8130D83-E684-5B6C-BDFE-EB6EE3CD49E8.dita">Writing a UPS Dialog Creator</xref>  </p> </li> <li id="GUID-5B659B40-818D-55F7-87AD-4144427DA52F"><p><xref href="GUID-CCD3B91F-9E7F-5CE2-8AFC-4ABF787E5614.dita">Using UPS management APIs</xref>  </p> </li> <li id="GUID-AAC1FF6D-6D4C-5548-B385-B672622A799D"><p>Example code at <filepath>\sf\os\security\authorisation\userpromptservice\examples\</filepath> location. </p> </li> </ul> </section> <section><title>See also</title> <p>For related information, see <xref href="GUID-6849E256-6719-5788-BCB2-7557F09AAAD0.dita">UPS Configuration</xref>. </p> </section> </conbody></concept>