Home | History | Annotate | Download | only in manifest 
      1 page.title=<permission>
      2 parent.title=The AndroidManifest.xml File
      3 parent.link=manifest-intro.html
      4 @jd:body
      5 
      6 <dl class="xml">
      7 <dt>syntax:</dt></dt>
      8 <dd><pre class="stx">&lt;permission android:<a href="#desc">description</a>="<i>string resource</i>"
      9             android:<a href="#icon">icon</a>="<i>drawable resource</i>"
     10             android:<a href="#label">label</a>="<i>string resource</i>"
     11             android:<a href="#nm">name</a>="<i>string</i>"
     12             android:<a href="#pgroup">permissionGroup</a>="<i>string</i>"
     13             android:<a href="#plevel">protectionLevel</a>=["normal" | "dangerous" | 
     14                                      "signature" | "signatureOrSystem"] /&gt;</pre></dd>
     15 
     16 <dt>contained in:</dt>
     17 <dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
     18 
     19 <dt>description:</dt>
     20 <dd>Declares a security permission that can be used to limit access 
     21 to specific components or features of this or other applications.  
     22 See the <a href="{@docRoot}guide/topics/manifest/manifest-intro.html#perms">Permissions</a>
     23 section in the introduction,
     24 and the <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a> 
     25 document for more information on how permissions work.</dd>
     26 
     27 <dt>attributes:</dt>
     28 <dd><dl class="attr">
     29 <dt><a name="desc"></a>{@code android:description}</dt>
     30 <dd>A user-readable description of the permission, longer and more 
     31 informative than the label.  It may be displayed to explain the 
     32 permission to the user &mdash; for example, when the user is asked 
     33 whether to grant the permission to another application.
     34 
     35 <p>
     36 This attribute must be set as a reference to a string resource; 
     37 unlike the {@code label} attribute, it cannot be a raw string.
     38 </p></dd>
     39 
     40 <dt><a name="icon"></a>{@code android:icon}</dt>
     41 <dd>A reference to a drawable resource for an icon that represents the 
     42 permission.</dd>
     43 
     44 <dt><a name="label"></a>{@code android:label}</dt>
     45 <dd>A name for the permission, one that can be displayed to users. 
     46 
     47 <p>
     48 As a convenience, the label can be directly set 
     49 as a raw string while you're developing the application.  However, 
     50 when the application is ready to be published, it should be set as a 
     51 reference to a string resource, so that it can be localized like other 
     52 strings in the user interface.
     53 </p></dd>
     54 
     55 <dt><a name="nm"></a>{@code android:name}</dt>
     56 <dd>The name of the permission.  This is the name that will be used in 
     57 code to refer to the permission &mdash; for example, in a 
     58 <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code> element and the
     59 {@code permission} attributes of application components.
     60 
     61 <p>
     62 The name must be unique, so it should use Java-style scoping &mdash; 
     63 for example, "{@code com.example.project.PERMITTED_ACTION}".
     64 </p></dd>
     65 
     66 <dt><a name="pgroup"></a>{@code android:permissionGroup}</dt>
     67 <dd>Assigns this permission to a group.  The value of this attribute is 
     68 the name of the group, which must be declared with the 
     69 <code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html">&lt;permission-group&gt;</a></code> element in this 
     70 or another application.  If this attribute is not set, the permission
     71 does not belong to a group.</dd>
     72 
     73 <dt><a name="plevel"></a>{@code android:protectionLevel}</dt>
     74 <dd>Characterizes the potential risk implied in the permission and
     75 indicates the procedure the system should follow when determining
     76 whether or not to grant the permission to an application requesting it. 
     77 The value can be set to one of the following strings:
     78 
     79 <table>
     80 <tr>
     81    <th>Value</th>
     82    <th>Meaning</th>
     83 </tr><tr>
     84    <td>"{@code normal}"</td>
     85    <td>The default value.  A lower-risk permission that gives requesting 
     86        applications access to isolated application-level features, with 
     87        minimal risk to other applications, the system, or the user.  
     88        The system automatically grants this type
     89        of permission to a requesting application at installation, without
     90        asking for the user's explicit approval (though the user always
     91        has the option to review these permissions before installing).
     92 </tr><tr>
     93    <td>"{@code dangerous}"</td>
     94    <td>A higher-risk permission that would give a requesting application
     95        access to private user data or control over the device that can
     96        negatively impact the user.  Because this type of permission
     97        introduces potential risk, the system may not automatically
     98        grant it to the requesting application.  For example, any dangerous
     99        permissions requested by an application may be displayed to the
    100        user and require confirmation before proceeding, or some other
    101        approach may be taken to avoid the user automatically allowing
    102        the use of such facilities.
    103 </tr><tr>
    104    <td>"{@code signature}"</td>
    105    <td>A permission that the system grants only if the requesting
    106        application is signed with the same certificate as the application
    107        that declared the permission. If the certificates match, the system
    108        automatically grants the permission without notifying the user or
    109        asking for the user's explicit approval.
    110 </tr><tr>
    111    <td>"{@code signatureOrSystem}"</td>
    112    <td>A permission that the system grants only to applications that are 
    113        in the Android system image <em>or</em> that are signed with the same
    114        certificates as those in the system image.  Please avoid using this 
    115        option, as the {@code signature} protection level should be sufficient 
    116        for most needs and works regardless of exactly where applications are 
    117        installed.  The "{@code signatureOrSystem}"
    118        permission is used for certain special situations where multiple
    119        vendors have applications built into a system image and need
    120        to share specific features explicitly because they are being built
    121        together.
    122 </tr>
    123 </table>
    124 </dd>
    125 </dl></dd>
    126 
    127 <!-- ##api level indication## -->
    128 <dt>introduced in:</dt>
    129 <dd>API Level 1</dd>
    130 
    131 <dt>see also:</dt>
    132 <dd><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code>
    133 <br/><code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html">&lt;permission-tree&gt;</a></code>
    134 <br/><code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html">&lt;permission-group&gt;</a></code></dd>
    135 </dd>
    136 
    137 </dl>
    138