[IT/VC] Installing a Search Provider and Setting the Default

Installing a Search Provider and Setting the Default

Windows Internet Explorer 8 extends a rich searching experience by offering users the option to install multiple search providers. As a user installs search providers, each provider has a chance to set itself as the default provider. Internet Explorer 8 has a new mandatory Search Provider Default user experience that keeps the user in control of their preferred search provider.

This article addresses best practices for setting a default search provider as you write your software to install your service.

In Internet Explorer 7, any program can write the GUID of their search provider to the DefaultScope registry key in HKCU\Software\Microsoft\Internet Explorer\SearchScopes to set the default search provider. Multiple programs can write (and monitor) this registry key, resulting in a confusing experience for the user when multiple programs write to this registry key and issue notification of changes.

To keep the user in control of their browser and their search preference, Internet Explorer 8 informs the user when a program wants to change the search default.

In Internet Explorer 8, writing the DefaultScope registry key still works, but (to keep the user in control) the user will see a dialog (the next time they open Internet Explorer) that informs them of a request to change the search default. The dialog box looks like this:

Figure 1: In this example, the user had the Fabrikam Search service as their default, and the Contoso Search software wrote a new setting to the DefaultScope registry key.

This dialog informs the user of the request, but does not give proper attribution to the source of the request.

We recommend that all software use the IOpenServiceManager APIs on Internet Explorer 8 and later to install a search provider and request that the user set it as their default. These APIs allow software to manage their search providers in a supported way that will not conflict with other software already installed on the user's machine. When software requests a search default change using these APIs, the source of the request is properly attributed in the dialog:

Figure 2: In this example, the software requests a search default change using the recommended SetDefault APIs and clear attribution is displayed. In this case, it is the Contoso.com Internet Search software.

This dialog is displayed as soon as the SetDefault API is called.

We strongly recommend that your software only use methods detailed in this article when setting a search default. Attempts to circumvent the Search Provider Default dialogs is considered inappropriate behavior.

The following code sample shows how to install a search provider and request that the user set it as the default.

Copy

#include <windows.h>
#include <atlbase.h>
#include <openservice.h>

    HRESULT hr = E_FAIL;
    BOOL fComInitialized = FALSE;

    if (S_OK == CoInitialize(NULL))
    {
        fComInitialized = TRUE;

        //Open a handle to the OpenService manager
        CComPtr<IOpenServiceManager> spManager;
        hr = spManager.CoCreateInstance(CLSID_OpenServiceManager);

        if (SUCCEEDED(hr))
        {
            CComPtr<IOpenService> spService;

            //Install my search provider
            //URL-OF-SERVICE: See http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_description_elements
            hr = spManager->InstallService(URL-OF-SERVICE, &spService);

            if (hr==S_OK)
            {
                //Request that the user change their search default
                hr = spService->SetDefault(TRUE, NULL);
            }
        }
    }

    if (fComInitialized)
    {
        CoUninitialize();
    }

Note that the SetDefault API will show a dialog (see Figure 2) requesting that the user change their search default. The user can approve or deny this request from the software during installation. If approved, the software can change the default setting. If denied, however, the software should not change user's default settings. The user can change this setting at any time by using the Manage Add-ons dialog.

If the binary that is calling the SetDefault API is signed with a valid code signing certificate, the program name and publisher will be displayed in the Search Provider Default dialog. We recommend code that calls SetDefault be signed.

Related Topics

• Search Provider Extensibility in Internet Explorer
• XML Search Suggestions Format Specification
• AddSearchProvider
• IsSearchProviderInstalled
• SetDefault
• Windows Search Guide
• OpenSearch Description