- From: laszlo gombos via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 19 May 2011 15:08:23 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/perms
In directory hutz:/tmp/cvs-serv22842
Added Files:
FeaturePermissions.xml
Log Message:
Copy baseline over from 2006/webapi/WebNotifications/source/FeaturePermissions.xml
--- NEW FILE: FeaturePermissions.xml ---
<specification
xmlns='http://berjon.com/ns/re-spec/'
xmlns:rs='http://berjon.com/ns/re-spec/'
version='1.0'
xml:lang='en'>
<metadata>
<title>Feature Permissions</title>
<styling type='W3C' status='ED'/>
<date year='2010' month='10' day='12'/>
<editors>
<person>
<name>John Gregg</name>
<email>johnnyg@google.com</email>
<company>Google</company>
<company-url>http://www.google.com/</company-url>
</person>
</editors>
</metadata>
<section xml:id='abstract' type='w3c-abstract'>
<title>Abstract</title>
<p>
This document defines APIs for web pages to request permission to use
privileged user agent features.
</p>
<!--
<ednote>
<p>
Last update: $Id: FeaturePermissions.xml,v 1.1 2011/05/19 15:08:21 lgombos Exp $.
</p>
</ednote>
-->
</section>
<section xml:id='sotd' type='w3c-sotd'>
<title>Status of this Document</title>
<p>
This document is an Editor's Draft and is not suitable for purposes other
than reviewing the specification being developed.
</p>
</section>
<section xml:id='contents' type='toc'>
<title>Table of Contents</title>
<?respec-toc?>
</section>
<section xml:id='definitions'>
<title>Definitions</title>
<ul>
<li><em>feature id</em>: A string which uniquely identifies a privileged feature.</li>
<li><em>privileged feature</em>: A feature of a user agent which requires the user's permission before web pages can use it.
Examples of privileged features may include desktop notifications, geolocation, file system access, etc.</li>
<li><em>origin</em>: In this document, "origin" or "security origin" refers to an origin as used by Cross-Origin Resource Sharing. [CORS]</li>
<li><em>user gesture</em>: A script event is considered a user gesture if it directly resulted from the user using an input device, and the event
is generated by the user agent, not a script. For example, the <code>onclick</code> event on an A element and the <code>onkeypress</code> event on
an INPUT element are user gestures. Scripts run by a timeout, or for example an <code>onload</code> event are not user gestures.</li>
</ul>
</section>
<section xml:id='introduction' normativity='not normative'>
<title>Introduction</title>
<p>
This specification provides an generic API for user agents which offer privileged
features to web pages in order to manage permissions in a consistent manner.
</p>
<p>
The purpose of the specification is to allow users to grant permission
to use individual privileged features to only the web pages which the user selects.
</p>
<p>
Permissions are granted and denied on a per-origin basis.
</p>
</section>
<section xml:id='idl-Permissions'>
<title>The Permissions interface</title>
<p>
The Permissions interface provides 3 pieces of functionality, which are added to the <code>Navigator</code> object.
<ul>
<li>
Identify the privileged features available in the user agent, using the <code>privilegedFeatures</code> array.
Each feature has a unique string identifier in the array.
</li>
<li>
Check the current permissions level of each feature for the current security origin, using the
<code>permissionLevel</code> method.
</li>
<li>
Request the user's permission to use a feature, using the <code>requestPermission</code> method, and
receive an asynchronous callback when the user has made a decision.
</li>
</ul>
</p>
<schema>
<title>Permissions</title>
<idl>
<interface name='Permissions'>
<definition-group for='permission values'>
<constant type='long' name='USER_ALLOWED' value='2' >
<p>
indicates that the user has granted permission.
</p>
</constant>
<constant type='long' name='DEFAULT_ALLOWED' value='1'>
<p>
indicates that the user has not made a permissions decision, but the user agent's
default policy is to allow permission.
</p>
</constant>
<constant type='long' name='DEFAULT_DENIED' value='-1'>
<p>
indicates that the user has not made a permissions decision, but the user agent's
default policy is to deny permission.
</p>
</constant>
<constant type='long' name='USER_DENIED' value='-2'>
<p>
indicates that the user has denied permission.
</p>
</constant>
</definition-group>
<method name='permissionLevel'>
<p>Returns the permission level of a feature.</p>
<param name='feature' type='String'>
A string containing a feature id.
</param>
<returns type='long'>
<p>
Returns one of the permission values <code>USER_ALLOWED</code>, <code>DEFAULT_ALLOWED</code>,
<code>DEFAULT_DENIED</code>, <code>USER_DENIED</code>.
</p>
</returns>
<exception name='Exception'>
<p>
If <code>feature</code> does not identify a feature known to the user agent,
the user agent must throw an exception.
</p>
</exception>
</method>
<method name='requestPermission'>
<param name='feature' type='String'>
A string containing a feature id.
</param>
<param name='callback' type='Function'>
A callback function to be called when the permission level is determined, such as
by the user responding to a permission dialog.
</param>
<p>
Requests that the user agent ask the user for permission for web pages from the
current security origin to use the feature identified by <code>feature</code>.
This method should only be called while handling a user gesture;
in other circumstances the user agent should take no action in response.
</p>
<p>
This method is asynchronous. The function provided in the <code>callback</code>
parameter will be invoked when the user has responded to the permission request.
</p>
<p>
If the current permission level is <code>DEFAULT_DENIED</code>, the user agent should
display a prompt to the user requesting permission for pages in the current security
origin to user the feature identified by <code>feature</code>, which allows the user
to allow or deny permission.
<blockquote>
<p>
If the user allows permission, the current permission level should change to
<code>USER_ALLOWED</code>, and the <code>callback</code> function should be called.
</p>
<p>
If the user denies permission, the current permission level should change to
<code>USER_DENIED</code>, and the <code>callback</code> function should be called.
</p>
</blockquote>
</p>
<p>
If the current permission level is <code>USER_ALLOWED</code>, <code>DEFAULT_ALLOWED</code>,
or <code>USER_DENIED</code>, the user agent should not prompt the user, and
call <code>callback</code> immediately.
</p>
<exception name='Exception'>
<p>
If <code>feature</code> does not identify a feature known to the user agent,
the user agent must throw an exception.
</p>
</exception>
</method>
<attribute name='privilegedFeatures' type='Array'>
<p>
Contains an array of strings which represent the valid feature identifiers that can be used in
<code>permissionLevel</code> and <code>requestPermission</code>.
</p>
</attribute>
</interface>
</idl>
<title>Permissions via Navigator</title>
<idl>
Navigator implements Permissions;
</idl>
</schema>
</section>
<section id='defaults'>
<title>Default permission levels</title>
<p>
The <code>Permissions</code> interface requires the user agent to indicate <code>DEFAULT_ALLOWED</code>
and <code>DEFAULT_DENIED</code> permission levels for feature/origin combinations where the user has
not made an explicit decision.
</p>
<p>
The purpose of the distinction between user-selected and default behavior is to allow the web page
to present appropriate user interfaces advising the user of the need for permission and what actions
should be taken to ensure permission is granted.
</p>
<p>
The user agent may select appropriate initial default settings for each feature, but must not indicate
<code>USER_ALLOWED</code> or <code>USER_DENIED</code> until the user has made a permissions decision.
</p>
</section>
<section>
<title>References</title>
<bibliography>
<bibentry xml:id='CORS'>
<title>Cross-Origin Resource Sharing</title>
<link>http://www.w3.org/TR/cors/</link>
</bibentry>
</bibliography>
</section>
</specification>
Received on Thursday, 19 May 2011 15:08:29 UTC