- From: poot <cvsmail@w3.org>
- Date: Thu, 25 Aug 2011 18:25:14 -0400
- To: public-html-diffs@w3.org
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 @@
<query> 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