AddSearchProvider method

Article
08/15/2017

Deprecated as of Internet Explorer 8.

Adds a search provider to the registry.

Syntax

HRESULT retVal = object.AddSearchProvider(URL);

Parameters

URL [in]
Type: BSTR

String that specifies an absolute or relative URL to the OpenSearch Description file for the search provider.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

Note As of Internet Explorer 10, this method only returns S_OK. In addition, this method is not supported for Windows Store apps using JavaScript and will fail silently if called.

AddSearchProvider was introduced in Windows Internet Explorer 7.

This method opens a dialog box that enables the user to add the provider to their registry, and optionally set it as the default search provider. The maximum number of search providers that can be installed is 200.

The URL parameter allows http:, https:, or ftp: protocol schemes only. Additionally, the URL must be in a security zone that permits downloading.

Search providers must use the HTTP GET request method; the POST request method is not supported.

Syntax of "Provider.xml" must be of valid XML format. Be sure to encode all characters in the query string. Perticularly, escaping "&" to "&".

The query string must contain "q={searchTerms}" somewhere within the query string. When Windows Internet Explorer 8 navigates to the provider to get search results, "{searchTerms}" will be replaced by the query string that the user typed into the Instant Search box.

When using an embedded link, the value of "rel" attribute must be set to "search" and the value of "type" attribute must be set to "application/opensearchdescription+xml".

Ensure the "title" advertised in the link tag represents the same string as the "ShortName" used by the XML description file. These strings must match to indicate that the provider has been installed. This will prevent users from installing your search provider multiple times under different names.

Examples

The following HTML implements a button that the user can click to install a search provider:

<INPUT TYPE="button" VALUE="Add Search Provider"
   onClick='window.external.AddSearchProvider("http://www.example.com/Provider.xml");'>

An alternative method is to make your search provider discoverable by adding an embedded link element within the head of your Web page. This will cause the search box drop-down arrow to turn orange. Rather then clicking a link or button that you provide, the user clicks on the orange arrow and chooses to install your search provider. The following HTML implements an embedded link:

<link title="My Provider Name" rel="search" type="application/opensearchdescription+xml" 
href="http://www.example.com/provider.xml">

The content of "Provider.xml" follows the OpenSearch Description file format. The following description file adds MSDN as a search provider:

<?xml version="1.0" encoding="UTF-8"?>
   <OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
      <ShortName>MSDN</ShortName>
      <Description>MSDN Search</Description>
      <Url type="text/html"
   template="http://search.msdn.microsoft.com/search/results.aspx?view=msdn&amp;q={searchTerms}" />  
   </OpenSearchDescription>

All OpenSearch Description file must include the search provider name and search URL. An optional element in the OpenSearch Description file is of the type "image/icon". When specified, the icon is displayed next to your provider name in the search box. We highly recommend that an icon is included. If Internet Explorer 8 cannot find an icon for your provider either in your description file or at the root of your web site, it will use a generic icon to represent your search provider in the QuickPick menu. To include an icon, add the following code snippet to your description file.

<Image height="16" width="16" type="image/icon">http://example.com/websearch.ico</Image>

A quick and easy way to generate OpenSearch Description file is to use a widget from the Windows Search Guide to Create You Own XML file. Follow the instructions in the widget and then click the "View XML" link from step 5. The widget will create the XML syntax similar to the code snippet above. Save the output to an XML file and then upload the file to your web server. Before uploading, however, make sure you have a valid XML file and that the "&" in your URL is escaped.

Starting from Internet Explorer 8, search suggestions are supported. With search suggestions, as the user is typing in the Instant Search box Internet Explorer 8 can send a request to your search provider with the current query string and you can supply suggestions which might enable the user to create a better search term. Internet Explorer 8 supports two search suggestions formats, a JSON format and an XML format. The JSON search suggestion format lets you send text based search suggestions which can be augmented with descriptions and URL. The XML search-suggestion format lets you send all the content available with JSON suggestions, as well as visual suggestions and section titles. For more information and samples of search suggestions, read this article on Search Provider Extensibility in Internet Explorer.To enable search suggestions, add the following code snippets to your OpenSearch Description file:

<Url type="application/x-suggestions+json" template="http://suggestions.example.com/?q={searchTerms}"/>
<Url type="application/x-suggestions+xml" template="http://suggestions.example.com/?q={searchTerms}"/>

Share via