hixie: Add an API to unregister a handler and an API to check if a handler is registered. (whatwg r6524)

hixie: Add an API to unregister a handler and an API to check if a
handler is registered. (whatwg r6524)

http://dev.w3.org/cvsweb/html5/spec/Overview.html?r1=1.5223&r2=1.5224&f=h
http://html5.org/tools/web-apps-tracker?from=6523&to=6524

===================================================================
RCS file: /sources/public/html5/spec/Overview.html,v
retrieving revision 1.5223
retrieving revision 1.5224
diff -u -d -r1.5223 -r1.5224
--- Overview.html 23 Aug 2011 23:28:09 -0000 1.5223
+++ Overview.html 25 Aug 2011 22:24:41 -0000 1.5224
@@ -321,7 +321,7 @@
 
    <h1>HTML5</h1>
    <h2 class="no-num no-toc" id="a-vocabulary-and-associated-apis-for-html-and-xhtml">A vocabulary and associated APIs for HTML and XHTML</h2>
-   <h2 class="no-num no-toc" id="editor-s-draft-23-august-2011">Editor's Draft 23 August 2011</h2>
+   <h2 class="no-num no-toc" id="editor-s-draft-25-august-2011">Editor's Draft 25 August 2011</h2>
    <dl><dt>Latest Published Version:</dt>
     <dd><a href="http://www.w3.org/TR/html5/">http://www.w3.org/TR/html5/</a></dd>
     <dt>Latest Editor's Draft:</dt>
@@ -467,7 +467,7 @@
   Group</a> is the W3C working group responsible for this
   specification's progress along the W3C Recommendation
   track.
-  This specification is the 23 August 2011 Editor's Draft.
+  This specification is the 25 August 2011 Editor's Draft.
   </p><!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><p>Work on this specification is also done at the <a href="http://www.whatwg.org/">WHATWG</a>. The W3C HTML working group
   actively pursues convergence with the WHATWG, as required by the <a href="http://www.w3.org/2007/03/HTML-WG-charter">W3C HTML working
   group charter</a>.</p><!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5
@@ -51575,6 +51575,10 @@
   // content handler registration
   void <a href="#dom-navigator-registerprotocolhandler" title="dom-navigator-registerProtocolHandler">registerProtocolHandler</a>(DOMString scheme, DOMString url, DOMString title);
   void <a href="#dom-navigator-registercontenthandler" title="dom-navigator-registerContentHandler">registerContentHandler</a>(DOMString mimeType, DOMString url, DOMString title);
+  DOMString <a href="#dom-navigator-isprotocolhandlerregistered" title="dom-navigator-isProtocolHandlerRegistered">isProtocolHandlerRegistered</a>(DOMString scheme, DOMString url);
+  DOMString <a href="#dom-navigator-iscontenthandlerregistered" title="dom-navigator-isContentHandlerRegistered">isContentHandlerRegistered</a>(DOMString mimeType, DOMString url);
+  void <a href="#dom-navigator-unregisterprotocolhandler" title="dom-navigator-unregisterProtocolHandler">unregisterProtocolHandler</a>(DOMString scheme, DOMString url);
+  void <a href="#dom-navigator-unregistercontenthandler" title="dom-navigator-unregisterContentHandler">unregisterContentHandler</a>(DOMString mimeType, DOMString url);
 };</pre><p>The <dfn id="dom-navigator-registerprotocolhandler" title="dom-navigator-registerProtocolHandler"><code>registerProtocolHandler()</code></dfn>
   method allows Web sites to register themselves as possible handlers
   for particular schemes. For example, an online telephone messaging
@@ -51626,9 +51630,9 @@
   <p>The arguments to the methods have the following meanings and
   corresponding implementation requirements. The requirements that
   involve throwing exceptions must be processed in the order given
-  below, stopping at the first exception raised. (So the
-  <code><a href="#security_err">SECURITY_ERR</a></code> exceptions take precedence over the
-  <code><a href="#syntax_err">SYNTAX_ERR</a></code> exception.)</p>
+  below, stopping at the first exception raised. (So the exceptions
+  for the first argument take precedence over the exceptions for the
+  second argument.)</p>
 
   <dl><dt><var title="">scheme</var> (<code title="dom-navigator-registerProtocolHandler"><a href="#dom-navigator-registerprotocolhandler">registerProtocolHandler()</a></code> only)</dt>
 
@@ -51702,7 +51706,7 @@
     <p>The following <a href="#mime-type" title="MIME type">MIME types</a> are in
     the <dfn id="type-blacklist">type blacklist</dfn>:</p>
 
-    <ul title="brief"><li><code><a href="#text-cache-manifest">text/cache-manifest</a></code></li>
+    <ul class="brief"><li><code><a href="#text-cache-manifest">text/cache-manifest</a></code></li>
      <li><code>text/css</code></li>
      <li><code><a href="#text-html-sandboxed">text/html-sandboxed</a></code></li>
      <li><code><a href="#text-html">text/html</a></code></li>
@@ -51728,11 +51732,36 @@
     <p>A string used to build the <a href="#url">URL</a> of the page that
     will handle the requests.</p>
 
-    <p>When the user agent uses this URL, it must replace the first
-    occurrence of the exact literal string "<code title="">%s</code>"
-    with an escaped version of the <a href="#absolute-url">absolute URL</a> of the
-    content in question (as defined below), then <a href="#resolve-a-url" title="resolve
-    a url">resolve</a> the resulting URL, relative to the <a href="#script-s-base-url" title="script's base URL">base URL</a> of the <a href="#entry-script">entry
+    <p>User agents must raise a <code><a href="#syntax_err">SYNTAX_ERR</a></code> exception if
+    the <var title="">url</var> argument passed to one of these
+    methods does not contain the exact literal string
+    "<code>%s</code>".</p>
+
+    <p>User agents must raise a <code><a href="#syntax_err">SYNTAX_ERR</a></code> if <a href="#resolve-a-url" title="resolve a url">resolving</a> the <var title="">url</var>
+    argument relative to the <a href="#entry-script">entry script</a>'s <a href="#script-s-base-url" title="script's base URL">base URL</a>, is not successful.</p>
+
+    <p class="note">The resulting <a href="#absolute-url">absolute URL</a> would by
+    definition not be a <a href="#valid-url">valid URL</a> as it would include the
+    string "<code title="">%s</code>" which is not a valid component
+    in a URL.</p>
+
+    <p>User agents must raise a <code><a href="#security_err">SECURITY_ERR</a></code> exception if
+    the resulting <a href="#absolute-url">absolute URL</a> has an <a href="#origin">origin</a>
+    that differs from the <a href="#origin">origin</a> of the <a href="#entry-script">entry
+    script</a>.</p>
+
+    <p class="note">This is forcibly the case if the <code title="">%s</code> placeholder is in the scheme, host, or port
+    parts of the URL.</p>
+
+    <p>The resulting <a href="#absolute-url">absolute URL</a> is the
+    <dfn id="proto-url">proto-URL</dfn>. It identifies the handler for the purposes
+    of the methods described below.</p>
+
+    <p>When the user agent uses this handler, it must replace the
+    first occurrence of the exact literal string "<code title="">%s</code>" in the <var title="">url</var> argument with
+    an escaped version of the <a href="#absolute-url">absolute URL</a> of the content
+    in question (as defined below), then <a href="#resolve-a-url" title="resolve a
+    url">resolve</a> the resulting URL, relative to the <a href="#script-s-base-url" title="script's base URL">base URL</a> of the <a href="#entry-script">entry
     script</a> at the time the <code title="dom-navigator-registerContentHandler"><a href="#dom-navigator-registercontenthandler">registerContentHandler()</a></code>
     or <code title="dom-navigator-registerProtocolHandler"><a href="#dom-navigator-registerprotocolhandler">registerProtocolHandler()</a></code>
     methods were invoked, and then <a href="#navigate">navigate</a> an appropriate <a href="#browsing-context">browsing context</a> to the
@@ -51745,14 +51774,6 @@
     &lt;query&gt; production defined in RFC 3986 by the
     percent-encoded form of that character. <a href="#refsRFC3986">[RFC3986]</a></p>
 
-    <p>User agents must raise a <code><a href="#syntax_err">SYNTAX_ERR</a></code> exception if
-    the <var title="">url</var> argument passed to one of these
-    methods does not contain the exact literal string
-    "<code>%s</code>", or if <a href="#resolve-a-url" title="resolve a
-    url">resolving</a> the <var title="">url</var> argument with
-    the first occurrence of the string "<code title="">%s</code>"
-    removed, relative to the <a href="#entry-script">entry script</a>'s <a href="#script-s-base-url" title="script's base URL">base URL</a>, is not successful.</p>
-
     <div class="example">
 
      <p>If the user had visited a site at <code title="">http://example.com/</code> that made the following
@@ -51801,7 +51822,191 @@
   part of any non-idempotent transaction), as the remote site would
   not be able to fetch the same data.</p>
 
-  </div><div class="impl">
+  <hr></div><p>In addition to the registration methods, there are also methods
+  for determining if particular handlers have been registered, and for
+  unregistering handlers.<dl class="domintro"><dt><var title="">state</var> = <var title="">window</var> . <code title="dom-navigator"><a href="#dom-navigator">navigator</a></code> . <code title="dom-navigator-isProtocolHandlerRegistered"><a href="#dom-navigator-isprotocolhandlerregistered">isProtocolHandlerRegistered</a></code>(<var title="">scheme</var>, <var title="">url</var>)</dt>
+   <dt><var title="">state</var> = <var title="">window</var> . <code title="dom-navigator"><a href="#dom-navigator">navigator</a></code> . <code title="dom-navigator-isContentHandlerRegistered"><a href="#dom-navigator-iscontenthandlerregistered">isContentHandlerRegistered</a></code>(<var title="">mimeType</var>, <var title="">url</var>)</dt>
+
+   <dd>
+
+    <p>Returns one of the following strings describing the state of
+    the handler given by the arguments:</p>
+
+    <dl><dt><code title="">new</code>
+     <dd>Indicates that no attempt has been made to register the given
+     handler (or that the handler has been unregistered). It would be
+     appropriate to promote the availability of the handler or to just
+     automatically register the handler.
+
+     <dt><code title="">registered</code>
+     <dd>Indicates that the given handler has been registered or that
+     the site is blocked from registering the handler. Trying to
+     register the handler again would have no effect.
+
+     <dt><code title="">declined</code>
+     <dd>Indicates that the given handler has been offered but was
+     rejected. Trying to register the handler again may prompt the
+     user again.
+
+    </dl></dd>
+
+   <dt><var title="">state</var> = <var title="">window</var> . <code title="dom-navigator"><a href="#dom-navigator">navigator</a></code> . <code title="dom-navigator-unregisterProtocolHandler"><a href="#dom-navigator-unregisterprotocolhandler">unregisterProtocolHandler</a></code>(<var title="">scheme</var>, <var title="">url</var>)</dt>
+   <dt><var title="">state</var> = <var title="">window</var> . <code title="dom-navigator"><a href="#dom-navigator">navigator</a></code> . <code title="dom-navigator-unregisterContentHandler"><a href="#dom-navigator-unregistercontenthandler">unregisterContentHandler</a></code>(<var title="">mimeType</var>, <var title="">url</var>)</dt>
+
+   <dd>
+
+    <p>Unregisters the handler given by the arguments.</p>
+
+   </dd>
+
+  </dl><div class="impl">
+
+  <p>The <dfn id="dom-navigator-isprotocolhandlerregistered" title="dom-navigator-isProtocolHandlerRegistered"><code>isProtocolHandlerRegistered()</code></dfn>
+  method must return the <a href="#handler-state-string">handler state string</a> that most
+  closely describes the current state of the handler described by the
+  two arguments to the method, where the first argument gives the
+  scheme and the second gives the string used to build the
+  <a href="#url">URL</a> of the page that will handle the requests.</p>
+
+  <p>The first argument must be compared to the schemes for which
+  custom protocol handlers are registered in an <a href="#ascii-case-insensitive">ASCII
+  case-insensitive</a> manner to find the relevant handlers.</p>
+
+  <p>The second argument must be preprocessed as described below, and
+  if that is successful, must then be matched against the <a href="#proto-url" title="proto-URL">proto-URLs</a> of the relevant handlers to find
+  the described handler.</p>
+
+  <hr><p>The <dfn id="dom-navigator-iscontenthandlerregistered" title="dom-navigator-isContentHandlerRegistered"><code>isContentHandlerRegistered()</code></dfn>
+  method must return the <a href="#handler-state-string">handler state string</a> that most
+  closely describes the current state of the handler described by the
+  two arguments to the method, where the first argument gives the
+  <a href="#mime-type">MIME type</a> and the second gives the string used to build
+  the <a href="#url">URL</a> of the page that will handle the requests.</p>
+
+  <p>The first argument must be compared to the <a href="#mime-type" title="MIME
+  type">MIME types</a> for which custom content handlers are
+  registered in an <a href="#ascii-case-insensitive">ASCII case-insensitive</a> manner to find
+  the relevant handlers.</p>
+
+  <p>The second argument must be preprocessed as described below, and
+  if that is successful, must then be matched against the
+  <a href="#proto-url" title="proto-URL">proto-URLs</a> of the relevant handlers to
+  find the described handler.</p>
+
+  <hr><p>The <dfn id="handler-state-string" title="handler state string">handler state strings</dfn>
+  are the following strings. Each string describes several situations,
+  as given by the following list.</p>
+
+  <dl><dt><code title="">new</code>
+
+   <dd>The described handler has never been registered for the given
+   scheme or type.
+
+   <dd>The described handler was once registered for the given scheme
+   or type, but the site has since unregistered it. If the handler
+   were to be reregistered, the user would be notified accordingly.
+
+   <dd>The described handler was once registered for the given scheme
+   or type, but the site has since unregistered it, but the user has
+   indicated that the site is to be blocked from registering the type
+   again, so the user agent would ignore further registration attempts.
+
+
+   <dt><code title="">registered</code>
+
+   <dd>An attempt was made to register the described handler for the
+   given scheme or type, but the user has not yet been notified, and
+   the user agent would ignore further registration attempts. (Maybe
+   the user agent batches registration requests to display them when
+   the user requests to be notified about them, and the user has not
+   yet requested that the user agent notify it of the previous
+   registration attempt.)
+
+   <dd>The described handler is registered for the given scheme or
+   type (maybe, or maybe not, as the default handler).
+
+   <dd>The described handler is permanently blocked from being
+   (re)registered. (Maybe the user marked the registration attempt as
+   spam, or blocked the site for other reasons.)
+
+
+   <dt><code title="">declined</code>
+
+   <dd>An attempt was made to register the described handler for the
+   given scheme or type, but the user has not yet been notified;
+   however, the user might be notified if another registration attempt
+   were to be made. (Maybe the last registration attempt was made
+   while the page was in the background and the user closed the page
+   without looking at it, and the user agent requires confirmation for
+   this registration attempt.)
+
+   <dd>An attempt was made to register the described handler for the
+   given scheme or type, but the user has not yet responded.
+
+   <dd>An attempt was made to register the described handler for the
+   given scheme or type, but the user declined the offer. The user has
+   not indicated that the handler is to be permanently blocked,
+   however, so another attempt to register the described handler might
+   result in the user being prompted again.
+
+   <dd>The described handler was once registered for the given scheme
+   or type, but the user has since removed it. The user has not
+   indicated that the handler is to be permanently blocked, however,
+   so another attempt to register the described handler might result
+   in the user being prompted again.
+
+  </dl><hr><p>The <dfn id="dom-navigator-unregisterprotocolhandler" title="dom-navigator-unregisterProtocolHandler"><code>unregisterProtocolHandler()</code></dfn>
+  method must unregister the handler described by the two arguments to
+  the method, where the first argument gives the scheme and the second
+  gives the string used to build the <a href="#url">URL</a> of the page that
+  will handle the requests.</p>
+
+  <p>The first argument must be compared to the schemes for which
+  custom protocol handlers are registered in an <a href="#ascii-case-insensitive">ASCII
+  case-insensitive</a> manner to find the relevant handlers.</p>
+
+  <p>The second argument must be preprocessed as described below, and
+  if that is successful, must then be matched against the <a href="#proto-url" title="proto-URL">proto-URLs</a> of the relevant handlers to find
+  the described handler.</p>
+
+  <hr><p>The <dfn id="dom-navigator-unregistercontenthandler" title="dom-navigator-unregisterContentHandler"><code>unregisterContentHandler()</code></dfn>
+  method must unregister the handler described by the two arguments to
+  the method, where the first argument gives the <a href="#mime-type">MIME
+  type</a> and the second gives the string used to build the
+  <a href="#url">URL</a> of the page that will handle the requests.</p>
+
+  <p>The first argument must be compared to the <a href="#mime-type" title="MIME
+  type">MIME types</a> for which custom content handlers are
+  registered in an <a href="#ascii-case-insensitive">ASCII case-insensitive</a> manner to find
+  the relevant handlers.</p>
+
+  <p>The second argument must be preprocessed as described below, and
+  if that is successful, must then be matched against the
+  <a href="#proto-url" title="proto-URL">proto-URLs</a> of the relevant handlers to
+  find the described handler.</p>
+
+  <hr><p>The second argument of the four methods described above must be
+  preprocessed as follows:</p>
+
+  <ol><li><p>If the string does not contain the substring "<code title="">%s</code>", abort these steps. There's no matching
+   handler.</li>
+
+   <li><p><a href="#resolve-a-url" title="resolve a URL">Resolve</a> the string
+   relative to the <a href="#script-s-base-url" title="script's base URL">base URL</a> of
+   the <a href="#entry-script">entry script</a>.</li>
+
+   <li><p>If this fails, then throw a <code><a href="#syntax_err">SYNTAX_ERR</a></code>
+   exception, aborting the method.</li>
+
+   <li><p>If the resoluting <a href="#absolute-url">absolute URL</a>'s
+   <a href="#origin">origin</a> is not the <a href="#same-origin">same origin</a> as that of
+   the <a href="#entry-script">entry script</a> throw a <a href="#security_err">SECURITY_ERR</a>
+   exception, aborting the method.</li>
+
+   <li><p>Return the resulting <a href="#absolute-url">absolute URL</a> as the result
+   of preprocessing the argument.</li>
+
+  </ol></div><div class="impl">
 
   <h5 id="security-and-privacy"><span class="secno">6.5.1.3 </span>Security and privacy</h5>

Received on Thursday, 25 August 2011 22:25:16 UTC