Skip to content

Commit

Permalink
[giow] (0) Add an API to unregister a handler and an API to check if …
Browse files Browse the repository at this point in the history 
…a handler is registered.

git-svn-id: http://svn.whatwg.org/webapps@6524 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information
@Hixie
Hixie committed Aug 25, 2011
1 parent 8a36e83 commit 931c9ad
Show file tree
Hide file tree
Showing 3 changed files with 721 additions and 56 deletions.
247 changes: 228 additions & 19 deletions complete.html
View file
Expand Up @@ -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> <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> <hgroup><h1>Web Applications 1.0</h1>
<h2 class="no-num no-toc">Living Standard &mdash; Last Updated 23 August 2011</h2> <h2 class="no-num no-toc">Living Standard &mdash; Last Updated 25 August 2011</h2>
</hgroup><dl><dt>Multiple-page version:</dt> </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> <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> <dt>One-page version:</dt>
Expand Down Expand Up @@ -70433,6 +70433,10 @@ <h5 id=custom-handlers><span class=secno>7.5.1.2 </span>Custom scheme and conten
// content handler registration // 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-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); 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> };</pre>


<p>The <dfn id=dom-navigator-registerprotocolhandler title=dom-navigator-registerProtocolHandler><code>registerProtocolHandler()</code></dfn> <p>The <dfn id=dom-navigator-registerprotocolhandler title=dom-navigator-registerProtocolHandler><code>registerProtocolHandler()</code></dfn>
Expand Down Expand Up @@ -70488,9 +70492,9 @@ <h5 id=custom-handlers><span class=secno>7.5.1.2 </span>Custom scheme and conten
<p>The arguments to the methods have the following meanings and <p>The arguments to the methods have the following meanings and
corresponding implementation requirements. The requirements that corresponding implementation requirements. The requirements that
involve throwing exceptions must be processed in the order given involve throwing exceptions must be processed in the order given
below, stopping at the first exception raised. (So the below, stopping at the first exception raised. (So the exceptions
<code><a href=#security_err>SECURITY_ERR</a></code> exceptions take precedence over the for the first argument take precedence over the exceptions for the
<code><a href=#syntax_err>SYNTAX_ERR</a></code> exception.)</p> second argument.)</p>


<dl><dt><var title="">scheme</var> (<code title=dom-navigator-registerProtocolHandler><a href=#dom-navigator-registerprotocolhandler>registerProtocolHandler()</a></code> only)</dt> <dl><dt><var title="">scheme</var> (<code title=dom-navigator-registerProtocolHandler><a href=#dom-navigator-registerprotocolhandler>registerProtocolHandler()</a></code> only)</dt>


Expand Down Expand Up @@ -70564,7 +70568,7 @@ <h5 id=custom-handlers><span class=secno>7.5.1.2 </span>Custom scheme and conten
<p>The following <a href=#mime-type title="MIME type">MIME types</a> are in <p>The following <a href=#mime-type title="MIME type">MIME types</a> are in
the <dfn id=type-blacklist>type blacklist</dfn>:</p> 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>text/css</code></li>
<li><code><a href=#text/html-sandboxed>text/html-sandboxed</a></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> <li><code><a href=#text/html>text/html</a></code></li>
Expand All @@ -70590,11 +70594,36 @@ <h5 id=custom-handlers><span class=secno>7.5.1.2 </span>Custom scheme and conten
<p>A string used to build the <a href=#url>URL</a> of the page that <p>A string used to build the <a href=#url>URL</a> of the page that
will handle the requests.</p> will handle the requests.</p>


<p>When the user agent uses this URL, it must replace the first <p>User agents must raise a <code><a href=#syntax_err>SYNTAX_ERR</a></code> exception if
occurrence of the exact literal string "<code title="">%s</code>" the <var title="">url</var> argument passed to one of these
with an escaped version of the <a href=#absolute-url>absolute URL</a> of the methods does not contain the exact literal string
content in question (as defined below), then <a href=#resolve-a-url title="resolve "<code>%s</code>".</p>
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> 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> 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> 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 methods were invoked, and then <a href=#navigate>navigate</a><!--DONAV
Expand All @@ -70608,14 +70637,6 @@ <h5 id=custom-handlers><span class=secno>7.5.1.2 </span>Custom scheme and conten
&lt;query&gt; production defined in RFC 3986 by the &lt;query&gt; production defined in RFC 3986 by the
percent-encoded form of that character. <a href=#refsRFC3986>[RFC3986]</a></p> 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> <div class=example>


<p>If the user had visited a site at <code title="">http://example.com/</code> that made the following <p>If the user had visited a site at <code title="">http://example.com/</code> that made the following
Expand Down Expand Up @@ -70664,7 +70685,195 @@ <h5 id=custom-handlers><span class=secno>7.5.1.2 </span>Custom scheme and conten
part of any non-idempotent transaction), as the remote site would part of any non-idempotent transaction), as the remote site would
not be able to fetch the same data.</p> 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> <div class=impl>
Expand Down

0 comments on commit 931c9ad

Please sign in to comment.