- From: laszlo gombos via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 19 May 2011 16:33:43 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/perms
In directory hutz:/tmp/cvs-serv15891
Added Files:
FeaturePermissions.html
Log Message:
Convert to ReSpec.js
--- NEW FILE: FeaturePermissions.html ---
<!DOCTYPE html>
<html>
<head>
<title>Feature Permissions</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<!--
=== NOTA BENE ===
For the three scripts below, if your spec resides on dev.w3 you can check them
out in the same tree and use relative links so that they'll work offline,
-->
<script src='../ReSpec.js/js/respec.js' class='remove'></script>
<script class='remove'>
var respecConfig = {
specStatus: "ED",
shortName: "perms",
// publishDate: "2010-10-12",
// previousPublishDate: "2010-10-12",
// previousMaturity: "ED",
edDraftURI: "http://dev.w3.org/2009/dap/perms/FeaturePermissions.html",
// lcEnd: "2010-10-12",
editors: [
{ name: "John Gregg", company: "Google", companyURL: "http://www.google.com/" },
{ name: "Laszlo Gombos", company: "Nokia", companyURL: "http://www.nokia.com/" }
],
inlineCSS: true,
noIDLIn: true,
extraCSS: ["../ReSpec.js/css/respec.css"],
wg: "Device APIs and Policy Working Group",
wgURI: "http://www.w3.org/2009/dap/",
wgPublicList: "public-device-apis",
wgPatentURI: "http://www.w3.org/2004/01/pp-impl/43696/status",
};
</script>
<style type='text/css'>
.event {
font-family: monospace;
color: #459900;
}
a.internalDFN:link, a.internalDFN:visited {
font-family: monospace;
border-bottom: 0;
color: #459900;
}
</style>
</head>
<body>
<section id='abstract'>
This document defines APIs for web pages to request permission to use
privileged user agent features.
</section>
<section id='definitions'>
<h2>Definitions</h2>
<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 id='introduction'>
<h2>Introduction</h2>
<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 id='idl-Permissions'>
<h2>The Permissions interface</h2>
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>
<h2>Permissions</h2>
<dl title='Navigator implements Permissions' class='idl'>
</dl>
<dl title='interface Permissions' class='idl'>
<dt>const long USER_ALLOWED = 2</dt>
<dd>
Indicates that the user has granted permission.
</dd>
<dt>const long DEFAULT_ALLOWED = 1</dt>
<dd>
Indicates that the user has not made a permissions decision, but the user agent's
default policy is to allow permission.
</dd>
<dt>const long DEFAULT_DENIED = -1</dt>
<dd>
Indicates that the user has not made a permissions decision, but the user agent's
default policy is to deny permission.
</dd>
<dt>const long USER_DENIED = -2</dt>
<dd>
Indicates that the user has denied permission.
</dd>
<dt>long permissionLevel (in String feature) raises(Exception)</dt>
<dd>
Returns the permission level of a feature.
<dl class='parameters'>
<dt>in String feature</dt>
<dd>
Returns one of the permission values <code>USER_ALLOWED</code>, <code>DEFAULT_ALLOWED</code>,
<code>DEFAULT_DENIED</code>, <code>USER_DENIED</code>.
</dd>
</dl>
<dl class='exception' title='Exception'>
<dt></dt>
<dd>
If <code>feature</code> does not identify a feature known to the user agent,
the user agent must throw an exception.
</dd>
</dl>
</dd>
<dt>void requestPermission (in String feature, in Function callback) raises(Exception)</dt>
<dd>
<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>
<dl class='parameters'>
<dt>in String feature</dt>
<dd>
A string containing a feature id.
</dd>
<dt>in Function callback</dt>
<dd>
A callback function to be called when the permission level is determined, such as
by the user responding to a permission dialog.
</dd>
</dl>
<dl class='exception' title='Exception'>
<dt></dt>
<dd>
If <code>feature</code> does not identify a feature known to the user agent,
the user agent must throw an exception.
</dd>
</dl>
</dd>
<dt>attribute Array privilegedFeatures</dt>
<dd>
Contains an array of strings which represent the valid feature identifiers that can be used in
<code>permissionLevel</code> and <code>requestPermission</code>.
</dd>
</dl>
</section>
<section>
<h2>Default permission levels</h2>
<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>
</body>
</html>
Received on Thursday, 19 May 2011 16:33:45 UTC