Short URL: http://html5.org/r/6524
| SVN | Bug | Comment | Time (UTC) |
|---|---|---|---|
| 6524 | 2011-08-25 22:23 |
Index: source
===================================================================
--- source (revision 6523)
+++ source (revision 6524)
@@ -80134,6 +80134,10 @@
// content handler registration
void <span title="dom-navigator-registerProtocolHandler">registerProtocolHandler</span>(DOMString scheme, DOMString url, DOMString title);
void <span title="dom-navigator-registerContentHandler">registerContentHandler</span>(DOMString mimeType, DOMString url, DOMString title);
+ DOMString <span title="dom-navigator-isProtocolHandlerRegistered">isProtocolHandlerRegistered</span>(DOMString scheme, DOMString url);
+ DOMString <span title="dom-navigator-isContentHandlerRegistered">isContentHandlerRegistered</span>(DOMString mimeType, DOMString url);
+ void <span title="dom-navigator-unregisterProtocolHandler">unregisterProtocolHandler</span>(DOMString scheme, DOMString url);
+ void <span title="dom-navigator-unregisterContentHandler">unregisterContentHandler</span>(DOMString mimeType, DOMString url);
};</pre>
<p>The <dfn
@@ -80198,9 +80202,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>SECURITY_ERR</code> exceptions take precedence over the
- <code>SYNTAX_ERR</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>
@@ -80281,7 +80285,7 @@
<p>The following <span title="MIME type">MIME types</span> are in
the <dfn>type blacklist</dfn>:</p>
- <ul title="brief">
+ <ul class="brief">
<li><code>text/cache-manifest</code></li>
<li><code>text/css</code></li>
@@ -80311,11 +80315,40 @@
<p>A string used to build the <span>URL</span> 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 <span>absolute URL</span> of the
- content in question (as defined below), then <span title="resolve
- a url">resolve</span> the resulting URL, relative to the <span
+ <p>User agents must raise a <code>SYNTAX_ERR</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>SYNTAX_ERR</code> if <span
+ title="resolve a url">resolving</span> the <var title="">url</var>
+ argument relative to the <span>entry script</span>'s <span
+ title="script's base URL">base URL</span>, is not successful.</p>
+
+ <p class="note">The resulting <span>absolute URL</span> would by
+ definition not be a <span>valid URL</span> 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>SECURITY_ERR</code> exception if
+ the resulting <span>absolute URL</span> has an <span>origin</span>
+ that differs from the <span>origin</span> of the <span>entry
+ script</span>.</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 <span>absolute URL</span> is the
+ <dfn>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 <span>absolute URL</span> of the content
+ in question (as defined below), then <span title="resolve a
+ url">resolve</span> the resulting URL, relative to the <span
title="script's base URL">base URL</span> of the <span>entry
script</span> at the time the <code
title="dom-navigator-registerContentHandler">registerContentHandler()</code>
@@ -80334,15 +80367,6 @@
percent-encoded form of that character. <a
href="#refsRFC3986">[RFC3986]</a></p>
- <p>User agents must raise a <code>SYNTAX_ERR</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 <span title="resolve a
- url">resolving</span> the <var title="">url</var> argument with
- the first occurrence of the string "<code title="">%s</code>"
- removed, relative to the <span>entry script</span>'s <span
- title="script's base URL">base URL</span>, is not successful.</p>
-
<div class="example">
<p>If the user had visited a site at <code
@@ -80397,11 +80421,234 @@
part of any non-idempotent transaction), as the remote site would
not be able to fetch the same data.</p>
+ <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.</p>
+ <dl class="domintro">
+
+ <dt><var title="">state</var> = <var title="">window</var> . <code title="dom-navigator">navigator</code> . <code title="dom-navigator-isProtocolHandlerRegistered">isProtocolHandlerRegistered</code>(<var title="">scheme</var>, <var title="">url</var>)</dt>
+ <dt><var title="">state</var> = <var title="">window</var> . <code title="dom-navigator">navigator</code> . <code title="dom-navigator-isContentHandlerRegistered">isContentHandlerRegistered</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">navigator</code> . <code title="dom-navigator-unregisterProtocolHandler">unregisterProtocolHandler</code>(<var title="">scheme</var>, <var title="">url</var>)</dt>
+ <dt><var title="">state</var> = <var title="">window</var> . <code title="dom-navigator">navigator</code> . <code title="dom-navigator-unregisterContentHandler">unregisterContentHandler</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
+ title="dom-navigator-isProtocolHandlerRegistered"><code>isProtocolHandlerRegistered()</code></dfn>
+ method must return the <span>handler state string</span> 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
+ <span>URL</span> 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 <span>ASCII
+ case-insensitive</span> 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 <span
+ title="proto-URL">proto-URLs</span> of the relevant handlers to find
+ the described handler.</p>
+
+ <hr>
+
+ <p>The <dfn
+ title="dom-navigator-isContentHandlerRegistered"><code>isContentHandlerRegistered()</code></dfn>
+ method must return the <span>handler state string</span> that most
+ closely describes the current state of the handler described by the
+ two arguments to the method, where the first argument gives the
+ <span>MIME type</span> and the second gives the string used to build
+ the <span>URL</span> of the page that will handle the requests.</p>
+
+ <p>The first argument must be compared to the <span title="MIME
+ type">MIME types</span> for which custom content handlers are
+ registered in an <span>ASCII case-insensitive</span> 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
+ <span title="proto-URL">proto-URLs</span> of the relevant handlers to
+ find the described handler.</p>
+
+ <hr>
+
+ <p>The <dfn 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
+ 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 <span>URL</span> 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 <span>ASCII
+ case-insensitive</span> 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 <span
+ title="proto-URL">proto-URLs</span> of the relevant handlers to find
+ the described handler.</p>
+
+ <hr>
+
+ <p>The <dfn
+ 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 <span>MIME
+ type</span> and the second gives the string used to build the
+ <span>URL</span> of the page that will handle the requests.</p>
+
+ <p>The first argument must be compared to the <span title="MIME
+ type">MIME types</span> for which custom content handlers are
+ registered in an <span>ASCII case-insensitive</span> 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
+ <span title="proto-URL">proto-URLs</span> 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.</p></li>
+
+ <li><p><span title="resolve a URL">Resolve</span> the string
+ relative to the <span title="script's base URL">base URL</span> of
+ the <span>entry script</span>.</p></li>
+
+ <li><p>If this fails, then throw a <code>SYNTAX_ERR</code>
+ exception, aborting the method.</p></li>
+
+ <li><p>If the resoluting <span>absolute URL</span>'s
+ <span>origin</span> is not the <span>same origin</span> as that of
+ the <span>entry script</span> throw a <span>SECURITY_ERR</span>
+ exception, aborting the method.</p></li>
+
+ <li><p>Return the resulting <span>absolute URL</span> as the result
+ of preprocessing the argument.</p></li>
+
+ </ol>
+
+ </div>
+
+
+ <div class="impl">
+
<h5>Security and privacy</h5>
<p>These mechanisms can introduce a number of concerns, in