[giow] (0) Define window.external and the SearchProvider APIs, since …

…they are implemented by several browsers to some extent. git-svn-id: http://svn.whatwg.org/webapps@6140 340c8d12-0b0e-0410-8428-c7bf67bfef74
whatwg · May 16, 2011 · 04cab94 · 04cab94
1 parent 6e71d46
commit 04cab94
Show file tree

Hide file tree

Showing 3 changed files with 479 additions and 30 deletions.
diff --git a/complete.html b/complete.html
@@ -239,7 +239,7 @@
 
   <header class=head id=head><p><a class=logo href=http://www.whatwg.org/ rel=home><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 &mdash; Last Updated 13 May 2011</h2>
+    <h2 class="no-num no-toc">Living Standard &mdash; Last Updated 16 May 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>
@@ -944,14 +944,16 @@ <h2 class="no-num no-toc" id=contents>Table of contents</h2>
      <li><a href=#simple-dialogs><span class=secno>7.4.1 </span>Simple dialogs</a></li>
      <li><a href=#printing><span class=secno>7.4.2 </span>Printing</a></li>
      <li><a href=#dialogs-implemented-using-separate-documents><span class=secno>7.4.3 </span>Dialogs implemented using separate documents</a></ol></li>
-   <li><a href=#system-state-and-capabilities:-the-navigator-object><span class=secno>7.5 </span>System state and capabilities: the <code>Navigator</code> object</a>
+   <li><a href=#system-state-and-capabilities><span class=secno>7.5 </span>System state and capabilities</a>
     <ol>
-     <li><a href=#client-identification><span class=secno>7.5.1 </span>Client identification</a></li>
-     <li><a href=#custom-handlers><span class=secno>7.5.2 </span>Custom scheme and content handlers</a>
+     <li><a href=#the-navigator-object><span class=secno>7.5.1 </span>The <code>Navigator</code> object</a>
       <ol>
-       <li><a href=#security-and-privacy><span class=secno>7.5.2.1 </span>Security and privacy</a></li>
-       <li><a href=#sample-handler-impl><span class=secno>7.5.2.2 </span>Sample user interface</a></ol></li>
-     <li><a href=#manually-releasing-the-storage-mutex><span class=secno>7.5.3 </span>Manually releasing the storage mutex</a></ol></ol></li>
+       <li><a href=#client-identification><span class=secno>7.5.1.1 </span>Client identification</a></li>
+       <li><a href=#custom-handlers><span class=secno>7.5.1.2 </span>Custom scheme and content handlers</a></li>
+       <li><a href=#security-and-privacy><span class=secno>7.5.1.3 </span>Security and privacy</a></li>
+       <li><a href=#sample-handler-impl><span class=secno>7.5.1.4 </span>Sample user interface</a></li>
+       <li><a href=#manually-releasing-the-storage-mutex><span class=secno>7.5.1.5 </span>Manually releasing the storage mutex</a></ol></li>
+     <li><a href=#the-external-interface><span class=secno>7.5.2 </span>The <code>External</code> interface</a></ol></ol></li>
  <li><a href=#editing><span class=secno>8 </span>User interaction</a>
   <ol>
    <li><a href=#the-hidden-attribute><span class=secno>8.1 </span>The <code>hidden</code> attribute</a></li>
@@ -60711,6 +60713,7 @@ <h3 id=the-window-object><span class=secno>6.2 </span>The <code><a href=#window>
 
   // the user agent
   readonly attribute <a href=#navigator>Navigator</a> <a href=#dom-navigator title=dom-navigator>navigator</a>; <!-- IE also has window.clientInformation === window.navigator -->
+  readonly attribute <a href=#external>External</a> <a href=#dom-external title=dom-external>external</a>;
   readonly attribute <a href=#applicationcache>ApplicationCache</a> <a href=#dom-applicationcache title=dom-applicationCache>applicationCache</a>;
 
   // user prompts
@@ -68537,7 +68540,9 @@ <h4 id=dialogs-implemented-using-separate-documents><span class=secno>7.4.3 </sp
 
 
 
-  <h3 id=system-state-and-capabilities:-the-navigator-object><span class=secno>7.5 </span>System state and capabilities: the <code><a href=#navigator>Navigator</a></code> object</h3>
+  <h3 id=system-state-and-capabilities><span class=secno>7.5 </span>System state and capabilities</h3>
+
+  <h4 id=the-navigator-object><span class=secno>7.5.1 </span>The <code><a href=#navigator>Navigator</a></code> object</h4>
 
   <div class=impl>
 
@@ -68584,7 +68589,7 @@ <h3 id=system-state-and-capabilities:-the-navigator-object><span class=secno>7.5
   </div>
 
 
-  <h4 id=client-identification><span class=secno>7.5.1 </span>Client identification</h4>
+  <h5 id=client-identification><span class=secno>7.5.1.1 </span>Client identification</h5>
 
   <pre class=idl>[Supplemental, NoInterfaceObject]
 interface <dfn id=navigatorid>NavigatorID</dfn> {<!--
@@ -68669,7 +68674,7 @@ <h4 id=client-identification><span class=secno>7.5.1 </span>Client identificatio
   </div>
 
 
-  <h4 id=custom-handlers><span class=secno>7.5.2 </span>Custom scheme and content handlers</h4>
+  <h5 id=custom-handlers><span class=secno>7.5.1.2 </span>Custom scheme and content handlers</h5>
 
   <pre class=idl>[Supplemental, NoInterfaceObject]
 interface <dfn id=navigatorcontentutils>NavigatorContentUtils</dfn> {
@@ -68871,7 +68876,7 @@ <h4 id=custom-handlers><span class=secno>7.5.2 </span>Custom scheme and content
 
   <div class=impl>
 
-  <h5 id=security-and-privacy><span class=secno>7.5.2.1 </span>Security and privacy</h5>
+  <h5 id=security-and-privacy><span class=secno>7.5.1.3 </span>Security and privacy</h5>
 
   <p>These mechanisms can introduce a number of concerns, in
   particular privacy concerns.</p>
@@ -68955,7 +68960,7 @@ <h5 id=security-and-privacy><span class=secno>7.5.2.1 </span>Security and privac
 
   <div class=impl>
 
-  <h5 id=sample-handler-impl><span class=secno>7.5.2.2 </span>Sample user interface</h5>
+  <h5 id=sample-handler-impl><span class=secno>7.5.1.4 </span>Sample user interface</h5>
 
   <p><i>This section is non-normative.</i></p>
 
@@ -69001,7 +69006,7 @@ <h5 id=sample-handler-impl><span class=secno>7.5.2.2 </span>Sample user interfac
 
 
 
-  <h4 id=manually-releasing-the-storage-mutex><span class=secno>7.5.3 </span>Manually releasing the storage mutex</h4>
+  <h5 id=manually-releasing-the-storage-mutex><span class=secno>7.5.1.5 </span>Manually releasing the storage mutex</h5>
 
   <pre class=idl>[Supplemental, NoInterfaceObject]
 interface <dfn id=navigatorstorageutils>NavigatorStorageUtils</dfn> {
@@ -69040,6 +69045,143 @@ <h4 id=manually-releasing-the-storage-mutex><span class=secno>7.5.3 </span>Manua
   </div>
 
 
+  <h4 id=the-external-interface><span class=secno>7.5.2 </span>The <code><a href=#external>External</a></code> interface</h4>
+
+  <div class=impl>
+
+  <p>The <dfn id=dom-external title=dom-external><code>external</code></dfn>
+  attribute of the <code><a href=#window>Window</a></code> interface must return an
+  instance of the <code><a href=#external>External</a></code> interface. The same object
+  must be returned each time.</p>
+
+  </div>
+
+  <pre class=idl>interface <dfn id=external>External</dfn> {
+  void <a href=#dom-external-addsearchprovider title=dom-external-AddSearchProvider>AddSearchProvider</a>(in DOMString engineURL);
+  unsigned long <a href=#dom-external-issearchproviderinstalled title=dom-external-IsSearchProviderInstalled>IsSearchProviderInstalled</a>(in DOMString engineURL);
+};</pre>
+
+  <dl class=domintro><dt><var title="">window</var> . <code title=dom-external><a href=#dom-external>external</a></code> . <code title=dom-external-AddSearchProvider><a href=#dom-external-addsearchprovider>AddSearchProvider</a></code>( <var title="">url</var> )</dt>
+   <dd>
+
+    <p>Adds the search engine described by the OpenSearch description
+    document at <var title="">url</var>. <a href=#refsOPENSEARCH>[OPENSEARCH]</a></p>
+
+    <p>The OpenSearch description document has to be on the same
+    server as the script that calls this method.</p>
+
+   </dd>
+
+   <dt><var title="">installed</var> = <var title="">window</var> . <code title=dom-external><a href=#dom-external>external</a></code> . <code title=dom-external-IsSearchProviderInstalled><a href=#dom-external-issearchproviderinstalled>IsSearchProviderInstalled</a></code>( <var title="">url</var> )</dt>
+   <dd>
+
+    <p>Returns a value based on comparing <var title="">url</var> to
+    the URLs of the results pages of the installed search engines.</p>
+
+    <dl><dt>0 <dd>None of the installed search engines match <var title="">url</var>.
+     <dt>1 <dd>One or more installed search engines match <var title="">url</var>, but none are the user's default search engine.
+     <dt>2 <dd>The user's default search engine matches <var title="">url</var>.
+    </dl><p>The <var title="">url</var> is compared to the URLs of the
+    results pages of the installed search engines using a prefix
+    match. Only results pages on the same domain as the script that
+    calls this method are checked.</p>
+
+   </dd>
+
+  </dl><p class=note>Another way of exposing search engines using
+  OpenSearch description documents is using a <code><a href=#the-link-element>link</a></code>
+  element with the <code title=rel-search><a href=#link-type-search>search</a></code> link
+  type.</p>
+
+  <div class=impl>
+
+   <p>The <dfn id=dom-external-addsearchprovider title=dom-external-AddSearchProvider><code>AddSearchProvider()</code></dfn>
+   method, when invoked, must run the following steps:</p>
+
+   <ol><li><p>Optionally, abort these steps. User agents may implement
+    the method as a stub method that never does anything, or may
+    arbitrarily ignore invocations with particular arguments for
+    security, privacy, or usability reasons.</li>
+
+    <li><p><a href=#resolve-a-url title="resolve a url">Resolve</a> the <var title="">scriptURL</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>.</li>
+
+    <li><p>If this fails, abort these steps.</li>
+
+    <li><p>If the <a href=#origin>origin</a> of the resulting <a href=#absolute-url>absolute
+    URL</a> is not the <a href=#same-origin title="same origin">same</a> as the
+    origin of the <a href=#entry-script>entry script</a>, then abort these
+    steps.</li>
+
+    <li><p>Process the resulting <a href=#absolute-url>absolute URL</a> as the
+    <a href=#url>URL</a> to an OpenSearch description document. <a href=#refsOPENSEARCH>[OPENSEARCH]</a></li>
+
+   </ol><p>The <dfn id=dom-external-issearchproviderinstalled title=dom-external-IsSearchProviderInstalled><code>IsSearchProviderInstalled()</code></dfn>
+   method, when invoked, must run the following steps:</p>
+
+   <ol><li><p>Optionally, return 0 and abort these steps. User agents may
+    implement the method as a stub method that never returns a
+    non-zero value, or may arbitrarily ignore invocations with
+    particular arguments for security, privacy, or usability
+    reasons.</li>
+
+    <li><p>If the <a href=#origin>origin</a> of the <a href=#entry-script>entry script</a>
+    is an opaque identifier (i.e. it has no host component), then
+    return 0 and abort these steps.</li>
+
+    <li><p>Let <var title="">host1</var> be the host component of the
+    <a href=#origin>origin</a> of the <a href=#entry-script>entry script</a>.</li>
+
+    <li><p><a href=#resolve-a-url title="resolve a url">Resolve</a> the <var title="">scriptURL</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>.</li>
+
+    <li><p>If this fails, return 0 and abort these steps.</li>
+
+    <li><p>Let <var title="">host2</var> be be the <a href=#url-host title=url-host>&lt;host&gt;</a> component of the resulting
+    <a href=#absolute-url>absolute URL</a>.</li>
+
+    <li>
+
+     <p>If the longest suffix in the Public Suffix List that matches
+     the end of <var title="">host1</var> is different than the
+     longest suffix in the Public Suffix List that matches the end of
+     <var title="">host2</var>, then return 0 and abort these steps.
+     <a href=#refsPSL>[PSL]</a></p>
+
+     <p>If the next domain component of <var title="">host1</var> and
+     <var title="">host2</var> after their common suffix are not the
+     same, then return 0 and abort these steps.</p>
+
+     <p>Domain labels must be compared after applying the IDNA ToASCII
+     algorithm to them, with both the AllowUnassigned and
+     UseSTD3ASCIIRules flags set, in an <a href=#ascii-case-insensitive>ASCII
+     case-insensitive</a> manner. <a href=#refsRFC3490>[RFC3490]</a></p>
+
+    </li>
+
+    <li><p>Let <var title="">search engines</var> be the list of
+    search engines known by the user agent and made available to the
+    user by the user agent for which the resulting <a href=#absolute-url>absolute
+    URL</a> is a <a href=#prefix-match>prefix match</a> of the search engine's
+    <a href=#url>URL</a>, if any. For search engines registered using
+    OpenSearch description documents, the <a href=#url>URL</a> of the
+    search engine corresponds to the URL given in a <code title="">Url</code> element whose <code title="">rel</code>
+    attribute is "<code title="">results</code>" (the default). <a href=#refsOPENSEARCH>[OPENSEARCH]</a></li>
+
+    <li><p>If <var title="">search engines</var> is empty, return 0
+    and abort these steps.</li>
+
+    <li><p>If the user's default search engine (as determined by the
+    user agent) is one of the search engines in <var title="">search
+    engines</var>, then return 2 and abort these steps.</li>
+
+    <li><p>Return 1.</li>
+
+   </ol></div>
+
+
 
   <h2 id=editing><span class=secno>8 </span><dfn>User interaction</dfn></h2>