W3C home > Mailing lists > Public > public-dap-commits@w3.org > May 2011

2009/dap/perms FeaturePermissions.xml,NONE,1.1

From: laszlo gombos via cvs-syncmail <cvsmail@w3.org>
Date: Thu, 19 May 2011 15:08:23 +0000
To: public-dap-commits@w3.org
Message-Id: <E1QN4pr-0005wi-J7@lionel-hutz.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 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Thursday, 19 May 2011 15:08:29 GMT