<?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-DB827750-6057-537E-8FE1-8F68BF2E9F99" xml:lang="en"><title>Writing

a UPS Policy File</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>UPS policy files are resource files that specify whether application requests

to access services are silently accepted or denied or whether they require

the user to be prompted. Each service has a policy file. The policy file lists

policies for various applications. </p>

<section id="GUID-F3D62C3E-D570-4DE2-ACED-0577D3923965"><title>Required Background</title> <p>Before you start writing a

UPS policy file, you must configure the UPS. For more information, see <xref href="GUID-6849E256-6719-5788-BCB2-7557F09AAAD0.dita">Configuring UPS</xref>. </p> </section>

<section id="GUID-10A7A574-4E57-45E3-8198-CD6D15EAC455"><title>Introduction</title> <p>The resource header file, <filepath>ups/policies.rh</filepath>,

defines the structures and constants required by User Prompt Service policy

files. </p> <p>Device creators can customise 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. </p> <p>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 id="GUID-7DFB9572-0E28-4D7A-9EF1-8A4DADFAA0B3"><title>Writing policy files</title> <p>Writing policy files include

the following: </p> <ul>

<li id="GUID-9FE188FC-A512-595A-848B-DA5A82F143AF"><p>Naming and location

of policy files </p> </li>

<li id="GUID-81096653-08DF-53F2-8CD9-D683BD8D9F97"><p>Policy resource </p> </li>

</ul> <p><b> Naming and location of policy files</b> </p> <p>UPS policy files

must be named <filepath>ups_&lt;systemserversid&gt;_&lt;serviceuid&gt;.rsc</filepath>.

They are stored in <filepath>z:\private\10283558\policies</filepath> or the

equivalent directory on the system drive. </p> <p>The <codeph>systemserversid</codeph> and

the <codeph>serviceuid</codeph> components of the policy file name are 8-digit,

zero-padded hexadecimal numbers. </p> <p><b>Policy resource </b> </p> <p>The

policy resource is made up of a header, followed by any number of policies.

Policies need to be ordered from most specific to least specific. </p> <codeblock id="GUID-679FBF44-5880-57B2-83EA-1A89DA0BBA9D" xml:space="preserve">RESOURCE POLICIES mypolicies

    {

    header = POLICY_HEADER 

        {

        // header definition

        };

        policies = 

            {

            POLICY

            {

            // definition of policy 1

            },

            POLICY

            {

            // definition of policy 2

            }

            // etc

            };

   }

</codeblock> <p>The following shows an example header: </p> <codeblock id="GUID-52773FA8-A3E1-51E2-8F12-675BE94A21E3" xml:space="preserve">header = POLICY_HEADER

 {

 // The major version number of THIS policy file.

 // When policy files are upgraded or eclipsed the UPS deletes all decision

 // records for the system server server SID and service ID where the major

 // version in the decision record is not equal to the major version

 // number in the policy file.

 majorversion = 0;

 // The minor version number of THIS policy file.

 minorversion = 0; 

 // Built-in (protected SID and loaded from Z drive) client applications

 // do not require authorisation from the UPS if the client has the correct

 // capabilities.

 authorisationpolicy = ECheckPostManufacture;

 //dialogcreator and policyevaluator UIDs

 dialogcreator = 0x10283694;

 policyevaluator = 0x10283698;

 };

</codeblock> </section>

<section id="GUID-7A571B93-A2B9-4B97-ACE9-8C70AABBB389"><title>Example of a policy file </title> <p>The following is an example

of a policy file: </p> <codeblock id="GUID-F5378D3D-02A5-536E-96D1-6BD240B3852E" xml:space="preserve">#include &lt;ups/policies.rh&gt;

// Identifies this as a UPS policy file

UID2 KUidUpsPolicyResourceFile

// Uniquely defines this policy file. The UID should be reserved using the Symbian Signed protected UID allocator.

UID3 0x01100001                    

RESOURCE POLICIES testpolicies

    {

    header = POLICY_HEADER

        {

        // Built-in (protected SID and loaded from Z drive) client applications

        // do not require authorisation from the UPS if the client has the correct

        // capabilities.

        authorisationpolicy = ECheckPostManufacture;

        dialogcreator = 0x10283694;

        policyevaluator = 0x10283698;

        };

    policies = 

        {

        POLICY

            {        

            // Silently accept this SID (By specifying only KYes in options field)

            sid_list = {0x01000030};

            destination = "*";

            options = KYes;

            },            

        POLICY

            {

            // Silently accept these SIDs for a specific destination

            sid_list = {0x01000031,0x01000032};

            destination = "*WLAN*";

            options = KYes;

            },            

        POLICY

            {

            // For protected SIDs enable the Always and Never options

   // if the client has the correct capability.

            sid_classes = KProtectedSids;

            systemserversecurity = ESystemServerSecurityPassed;

            destination = "*";

            options = KYes|KNo|KAlways|KNever;

            policyevaluator = 0x01000020;

            dialogcreator = 0x01000021;

            },

        POLICY

            {

            // Unprotected SIDs may only get one-shot permissions            

            sid_classes = KUnprotectedSids;

            destination = "*";

            options = KYes|KNo;

            flags = 42;         // Flags specific to policy evaluator 0x10283698

            }

        };

    }

</codeblock> </section>

<section id="GUID-C069700D-FABD-4C84-AD71-B292F3B26E04"><title>See also</title><p><xref href="GUID-4E838A77-C7B5-5B1F-93F5-F3577901914B.dita">Policy

Resource</xref>  </p> </section>