Symbian3/PDK/Source/GUID-DB827750-6057-537E-8FE1-8F68BF2E9F99.dita
changeset 1 25a17d01db0c
child 3 46218c8b8afa
equal deleted inserted replaced
0:89d6a7a84779 1:25a17d01db0c
       
     1 <?xml version="1.0" encoding="utf-8"?>
       
     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
       
     3 <!-- This component and the accompanying materials are made available under the terms of the License 
       
     4 "Eclipse Public License v1.0" which accompanies this distribution, 
       
     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
       
     6 <!-- Initial Contributors:
       
     7     Nokia Corporation - initial contribution.
       
     8 Contributors: 
       
     9 -->
       
    10 <!DOCTYPE concept
       
    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
       
    12 <concept id="GUID-DB827750-6057-537E-8FE1-8F68BF2E9F99" xml:lang="en"><title>Writing
       
    13 a UPS Policy File</title><prolog><metadata><keywords/></metadata></prolog><conbody>
       
    14 <p>UPS policy files are resource files that specify whether application requests
       
    15 to access services are silently accepted or denied or whether they require
       
    16 the user to be prompted. Each service has a policy file. The policy file lists
       
    17 policies for various applications. </p>
       
    18 <section><title>Required Background</title> <p>Before you start writing a
       
    19 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>
       
    20 <section><title>Introduction</title> <p>The resource header file, <filepath>ups/policies.rh</filepath>,
       
    21 defines the structures and constants required by User Prompt Service policy
       
    22 files. </p> <p>Device creators can customise the circumstances under which
       
    23 prompts are generated by configuring policies. Policies are made up of details
       
    24 about the service being requested as well as information about whether to
       
    25 accept or deny silently or to ask the user. They are defined in policy lists.
       
    26 Each service has one policy list defining any number of policies. </p> <p>In
       
    27 cases where the policy specifies that a user prompt is required, ECOM plug-ins
       
    28 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
       
    29 by device creators. </p> </section>
       
    30 <section><title>Writing policy files</title> <p>Writing policy files include
       
    31 the following: </p> <ul>
       
    32 <li id="GUID-9FE188FC-A512-595A-848B-DA5A82F143AF"><p>Naming and location
       
    33 of policy files </p> </li>
       
    34 <li id="GUID-81096653-08DF-53F2-8CD9-D683BD8D9F97"><p>Policy resource </p> </li>
       
    35 </ul> <p><b> Naming and location of policy files</b> </p> <p>UPS policy files
       
    36 must be named <filepath>ups_&lt;systemserversid&gt;_&lt;serviceuid&gt;.rsc</filepath>.
       
    37 They are stored in <filepath>z:\private\10283558\policies</filepath> or the
       
    38 equivalent directory on the system drive. </p> <p>The <codeph>systemserversid</codeph> and
       
    39 the <codeph>serviceuid</codeph> components of the policy file name are 8-digit,
       
    40 zero-padded hexadecimal numbers. </p> <p><b>Policy resource </b> </p> <p>The
       
    41 policy resource is made up of a header, followed by any number of policies.
       
    42 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
       
    43     {
       
    44     header = POLICY_HEADER 
       
    45         {
       
    46         // header definition
       
    47         };
       
    48         policies = 
       
    49             {
       
    50             POLICY
       
    51             {
       
    52             // definition of policy 1
       
    53             },
       
    54             POLICY
       
    55             {
       
    56             // definition of policy 2
       
    57             }
       
    58             // etc
       
    59             };
       
    60    }
       
    61 </codeblock> <p>The following shows an example header: </p> <codeblock id="GUID-52773FA8-A3E1-51E2-8F12-675BE94A21E3" xml:space="preserve">header = POLICY_HEADER
       
    62  {
       
    63  // The major version number of THIS policy file.
       
    64  // When policy files are upgraded or eclipsed the UPS deletes all decision
       
    65  // records for the system server server SID and service ID where the major
       
    66  // version in the decision record is not equal to the major version
       
    67  // number in the policy file.
       
    68  majorversion = 0;
       
    69  // The minor version number of THIS policy file.
       
    70  minorversion = 0; 
       
    71 
       
    72  // Built-in (protected SID and loaded from Z drive) client applications
       
    73  // do not require authorisation from the UPS if the client has the correct
       
    74  // capabilities.
       
    75  authorisationpolicy = ECheckPostManufacture;
       
    76  //dialogcreator and policyevaluator UIDs
       
    77  dialogcreator = 0x10283694;
       
    78  policyevaluator = 0x10283698;
       
    79  };
       
    80 </codeblock> </section>
       
    81 <section><title>Example of a policy file </title> <p>The following is an example
       
    82 of a policy file: </p> <codeblock id="GUID-F5378D3D-02A5-536E-96D1-6BD240B3852E" xml:space="preserve">// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
       
    83 // All rights reserved.
       
    84 // This component and the accompanying materials are made available
       
    85 // under the terms of the License "Symbian Foundation License v1.0"
       
    86 // which accompanies this distribution, and is available
       
    87 // at the URL "http://www.symbianfoundation.org/legal/sfl-v10.html".
       
    88 //
       
    89 // Initial Contributors:
       
    90 // Nokia Corporation - initial contribution.
       
    91 
       
    92 
       
    93 #include &lt;ups/policies.rh&gt;
       
    94 // Identifies this as a UPS policy file
       
    95 UID2 KUidUpsPolicyResourceFile
       
    96 // Uniquely defines this policy file. The UID should be reserved using the Symbian Signed protected UID allocator.
       
    97 UID3 0x01100001                    
       
    98 
       
    99 RESOURCE POLICIES testpolicies
       
   100     {
       
   101     header = POLICY_HEADER
       
   102         {
       
   103         // Built-in (protected SID and loaded from Z drive) client applications
       
   104         // do not require authorisation from the UPS if the client has the correct
       
   105         // capabilities.
       
   106         authorisationpolicy = ECheckPostManufacture;
       
   107         dialogcreator = 0x10283694;
       
   108         policyevaluator = 0x10283698;
       
   109         };
       
   110     policies = 
       
   111         {
       
   112         POLICY
       
   113             {        
       
   114             // Silently accept this SID (By specifying only KYes in options field)
       
   115             sid_list = {0x01000030};
       
   116             destination = "*";
       
   117             options = KYes;
       
   118             },            
       
   119         POLICY
       
   120             {
       
   121             // Silently accept these SIDs for a specific destination
       
   122             sid_list = {0x01000031,0x01000032};
       
   123             destination = "*WLAN*";
       
   124             options = KYes;
       
   125             },            
       
   126         POLICY
       
   127             {
       
   128             // For protected SIDs enable the Always and Never options
       
   129    // if the client has the correct capability.
       
   130             sid_classes = KProtectedSids;
       
   131             systemserversecurity = ESystemServerSecurityPassed;
       
   132             destination = "*";
       
   133             options = KYes|KNo|KAlways|KNever;
       
   134             policyevaluator = 0x01000020;
       
   135             dialogcreator = 0x01000021;
       
   136             },
       
   137         POLICY
       
   138             {
       
   139             // Unprotected SIDs may only get one-shot permissions            
       
   140             sid_classes = KUnprotectedSids;
       
   141             destination = "*";
       
   142             options = KYes|KNo;
       
   143             flags = 42;         // Flags specific to policy evaluator 0x10283698
       
   144             }
       
   145         };
       
   146     }
       
   147 
       
   148 </codeblock> </section>
       
   149 <section><title>See also</title> <p><xref href="GUID-4E838A77-C7B5-5B1F-93F5-F3577901914B.dita">Policy
       
   150 Resource</xref>  </p> </section>
       
   151 </conbody></concept>