<?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-E56E21A9-B545-5217-A877-E64D30275157" xml:lang="en"><title>Policy

Evaluator Plug-in</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This section explains the user prompting function in the Messaging Middleware

module. It also explains how to extract the serial buffer from the various

Message Type Modules (MTM) of messaging components to the User Prompt Service

(UPS) Policy Evaluator plug-in. </p>

<section id="GUID-8AD9A61F-1BA4-498E-9886-21FCD5EBCA5D"><title>Overview</title> <p>The Messaging Middleware module enables

the users to automatically request the user's permission for sending messages.

The user's permission for outbound messages depends on the capability of the

client application that sends the email or SMS message. The phone users are

prompted to decide if any activity that can be billed (for example, sending

an email message or an SMS message) must be allowed or not. The phone user

is prompted with a dialog box to allow or deny the operation, and to choose

if that decision should apply to one operation, or always for a particular

client application. </p> <p>If the client application uses the SendAs server

to send email or SMS messages, then the user is prompted at the SendAs server

stage only and not at the server MTM stage. This behaviour can be configured

at ROM build time. </p> <p><b>Configuration</b> </p> <p>At ROM build time,

the phone manufacturers can configure the following: </p> <ul>

<li id="GUID-DB05B857-3581-5868-AFA8-BA94D85ADCE7"><p>The scope of the permission

granted to send email or SMS messages; that is, for one operation only or

always for a particular client application. </p> </li>

<li id="GUID-69B12279-9ECE-5D20-89FB-6C1CE76AB9AA"><p>Whether the user is

prompted for processes that have the network services capability, or not. </p> </li>

<li id="GUID-2A1E3811-E3C4-500C-BA51-C320772B5052"><p>Whether the user is

prompted for processes that do not have the network services capability, or

not. </p> </li>

</ul> </section>

<section id="GUID-34A30058-A9BD-4C88-823A-DFF24B638C41"><title>Architecture</title> <p>The request to send email or SMS messages

from a UI application and SendAs servers is passed from a client MTM to the

Message Server, on to the corresponding server MTM, and then to UPS. </p> <p>UPS

uses the Policy Evaluator plug-in, which allows a security decision to be

specific to an individual UI application. The Policy Evaluator plug-in prompts

the phone user (using the Dialog creator plug-in) for permission to send a

message, if the client application does not have the correct capability set. </p> <fig id="GUID-3A131C1E-CAA8-554A-A9A0-119E762D174C">

<title>              User prompting service architecture            </title>

</fig> <dl>

<dlentry>

<dt>UPS</dt>

<dd><p>User Prompt Service </p> <p>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 the user is required

to confirm the request. For more information on UPS, see <xref href="GUID-1A5C7320-B017-5CD9-B3EA-1301CC08A762.dita">User

Prompt Service overview</xref>. </p> </dd>

</dlentry>

<dlentry>

<dt>SendAs server</dt>

<dd><p>The following are some of the important SendAs server features: </p> <ul>

<li id="GUID-719A5CF7-2026-593D-8C36-36D57B6EDFFD"><p>Send a message after

the capability policing of the client application has been completed. </p> <p>For

more information on capability policing, see the <xref href="GUID-4BFEDD79-9502-526A-BA7B-97550A6F0601.dita">Platform

Security</xref> guide. </p> </li>

<li id="GUID-F6FB396F-3CC8-5277-896D-8FFE8333B163"><p>Allow client applications

to launch an editor for a specified message type. </p> </li>

<li id="GUID-00D7ABFC-E671-5CDA-A33D-8029E3A97631"><p>Allow client applications

to query the message type. </p> </li>

</ul> <p>For more information on SendAs server, see <xref href="GUID-63816E09-46C7-503A-ADA0-E350C7ACF3C4.dita">SendAs</xref>. </p> </dd>

</dlentry>

<dlentry>

<dt>Policy Evaluator</dt>

<dd><p>Policy Evaluator is an ECOM plug-in, which is responsible for generating

fingerprints used to locate previous decision records related to the request.

A default Policy Evaluator is provided by the Symbian platform,

but device creators can also write a Policy Evaluator. For more information

on Policy Evaluator, see <xref href="GUID-43080A86-72D3-5422-953E-A5EF79961D7B.dita">Writing

a UPS Policy Evaluators</xref>. </p> </dd>

</dlentry>

<dlentry>

<dt>Dialog creator</dt>

<dd><p>Dialog creator is an ECOM plug-in, which generates and displays dialog

prompts. Device creators define the Dialog creator plug-in. For more information

on Dialog creator, see <xref href="GUID-A8130D83-E684-5B6C-BDFE-EB6EE3CD49E8.dita">Writing

a UPS Dialog Creator</xref>. </p> </dd>

</dlentry>

</dl> </section>

<section id="GUID-6E1B9063-7E2E-4710-924A-598AD03FC007"><title>Implementation consideration</title> <p>The device creator

must implement the Policy Evaluator and Dialog creator plug-ins to get the

full functionality of the UPS service. </p> <p>The Policy Evaluator plug-in

can use the destination parameter to check if a particular request made by

a client application is permissible for a particular destination. </p> <p>Message

Server that interact with the UPS service can pass the destination parameter

(phone number, server address, and so on.) as a <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC</apiname></xref> descriptor.

If there is more than one parameter, the Message Server serialises the list

of addresses to a <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC           </apiname></xref> descriptor. </p> <p>To

enable the device creator to use this data, the Policy Evaluator plug-in must

convert <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC</apiname></xref> to an address list. </p> </section>

<section id="GUID-AE64C9C4-4B75-4E2C-9B3B-5BDD2DE282BD"><title>Extracting the serial buffer</title> <p>The following code

snippet shows how to convert the <xref href="GUID-FB97E0A3-352A-316F-97C6-69E4741A8120.dita"><apiname>TDesC8</apiname></xref> descriptor to the

address list. When the <xref href="GUID-AD05E838-D8AD-366B-B5F9-5FC061414D7C.dita#GUID-AD05E838-D8AD-366B-B5F9-5FC061414D7C/GUID-899D2AE8-E495-3718-BFDF-96328F436B00"><apiname>CPromptRequest::Destination()</apiname></xref> method

is called, it returns a <codeph>const</codeph>  <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC</apiname></xref> reference,

which contains the externalized destination values. </p> <p>In order to internalize

this <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC</apiname></xref>, the plug-in needs to implement the <xref href="GUID-2D8EC1BB-F8FC-3A6A-A953-4303FB2B0222.dita"><apiname>Internalise()</apiname></xref> functionality

using the following method: </p> <codeblock id="GUID-A6730A8E-D3BA-5E84-81D1-4A97D53B6AFF" xml:space="preserve">void InternaliseDestinationParameterL ()

        {    

         const TDesC& d = iRequest->Destination(); // iRequest is a pointer of type CPromptRequest

         TPtrC8 p(reinterpret_cast<const TUint8*>(d.Ptr()), d.Length() * 2);

         RDesReadStream readStream(p);

         InternalizeL(readStream);

        }

InternalizeL (RReadStream& aStream)

        {

         TInt count = aStream.ReadInt32L ();

         RArray<TPtrC> destinationArray;

         TBuf<1000 > destination ; // 1000 since this is the maximum length if the header info of a mail

         for(TInt I=0;i< count;++I)

               {

                aStream >> destination;

                destinationArray.Append(destination);

               }

        }

</codeblock> <p>The device creator can now use the extracted serial buffer

for displaying dialog prompts. </p> </section>

</conbody><related-links>

<link href="GUID-33C7EEEB-88B8-5587-916D-2C5D122F6010.dita"><linktext>SMS     

           MTM</linktext></link>

<link href="GUID-4384066E-158A-5F63-A823-7793DAE680BF.dita"><linktext>Email</linktext>

</link>

</related-links></concept>