[html5] r6524 - [giow] (0) Add an API to unregister a handler and an API to check if a handler i [...]
whatwg at whatwg.org
whatwg at whatwg.org
Thu Aug 25 15:23:43 PDT 2011
Author: ianh
Date: 2011-08-25 15:23:41 -0700 (Thu, 25 Aug 2011)
New Revision: 6524
Modified:
complete.html
index
source
Log:
[giow] (0) Add an API to unregister a handler and an API to check if a handler is registered.
Modified: complete.html
===================================================================
--- complete.html 2011-08-23 23:27:17 UTC (rev 6523)
+++ complete.html 2011-08-25 22:23:41 UTC (rev 6524)
@@ -239,7 +239,7 @@
<header class=head id=head><p><a class=logo href=http://www.whatwg.org/><img alt=WHATWG height=101 src=/images/logo width=101></a></p>
<hgroup><h1>Web Applications 1.0</h1>
- <h2 class="no-num no-toc">Living Standard — Last Updated 23 August 2011</h2>
+ <h2 class="no-num no-toc">Living Standard — Last Updated 25 August 2011</h2>
</hgroup><dl><dt>Multiple-page version:</dt>
<dd><a href=http://www.whatwg.org/specs/web-apps/current-work/complete/>http://www.whatwg.org/specs/web-apps/current-work/complete/</a></dd>
<dt>One-page version:</dt>
@@ -70433,6 +70433,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>
@@ -70488,9 +70492,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>
@@ -70564,7 +70568,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>
@@ -70590,11 +70594,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><!--DONAV
@@ -70608,14 +70637,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
@@ -70664,9 +70685,197 @@
part of any non-idempotent transaction), as the remote site would
not be able to fetch the same data.</p>
- </div>
+ <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><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>7.5.1.3 </span>Security and privacy</h5>
Modified: index
===================================================================
--- index 2011-08-23 23:27:17 UTC (rev 6523)
+++ index 2011-08-25 22:23:41 UTC (rev 6524)
@@ -243,7 +243,7 @@
<header class=head id=head><p><a class=logo href=http://www.whatwg.org/><img alt=WHATWG height=101 src=/images/logo width=101></a></p>
<hgroup><h1 class=allcaps>HTML</h1>
- <h2 class="no-num no-toc">Living Standard — Last Updated 23 August 2011</h2>
+ <h2 class="no-num no-toc">Living Standard — Last Updated 25 August 2011</h2>
</hgroup><dl><dt><strong>Web developer edition</strong></dt>
<dd><strong><a href=http://developers.whatwg.org/>http://developers.whatwg.org/</a></strong></dd>
<dt>Multiple-page version:</dt>
@@ -70323,6 +70323,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>
@@ -70378,9 +70382,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>
@@ -70454,7 +70458,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>
@@ -70480,11 +70484,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><!--DONAV
@@ -70498,14 +70527,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
@@ -70554,9 +70575,197 @@
part of any non-idempotent transaction), as the remote site would
not be able to fetch the same data.</p>
- </div>
+ <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><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>7.5.1.3 </span>Security and privacy</h5>
Modified: source
===================================================================
--- source 2011-08-23 23:27:17 UTC (rev 6523)
+++ source 2011-08-25 22:23:41 UTC (rev 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
More information about the Commit-Watchers
mailing list