<?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>
</conbody></concept>