nsIBrowserSearchService

Implemented by: @mozilla.org/browser/search-service;1. To access this service, use:

var browserSearchService = Components.classes["@mozilla.org/browser/search-service;1"]
                           .getService(Components.interfaces.nsIBrowserSearchService);

Method overview

Attributes

Methods

addEngine()

Adds a new search engine from the file at the supplied URI, optionally asking the user for confirmation first. If a confirmation dialog is shown, it will offer the option to begin using the newly added engine right away; if no confirmation dialog is shown, the new engine will be used right away automatically.

void addEngine(
  in AString engineURL,
  in long dataType,
  in AString iconURL,
  in boolean confirm,
  [optional] in nsISearchInstallCallback callback
);

Parameters

engineURL

The URL to the search engine's description file.

dataType

An integer representing the plugin file format. Must be one of the supported search engine data types defined above.

iconURL

A URL string to an icon file to be used as the search engine's icon. This value may be overridden by an icon specified in the engine description file.

confirm

A boolean value indicating whether the user should be asked for confirmation before this engine is added to the list. If this value is false, the engine will be added to the list upon successful load, but it will not be selected as the current engine.

callback

A nsISearchInstallCallback that will be notified when the addition is complete, or if the addition fails. It will not be called if addEngine throws an exception.

Exceptions thrown

NS_ERROR_FAILURE

If the type is invalid, or if the description file cannot be successfully loaded.

addEngineWithDetails()

Adds a new search engine, without asking the user for confirmation and without starting to use it right away.

void addEngineWithDetails(
  in AString name,
  in AString iconURL,
  in AString alias,
  in AString description,
  in AString method,
  in AString url
);

Parameters

name

The search engine's name. Must be unique. Must not be null.

iconURL

Optional: A URL string pointing to the icon to be used to represent the engine.

alias

Optional: A unique shortcut that can be used to retrieve the search engine.

description

Optional: a description of the search engine.

method

The HTTP request method used when submitting a search query. Must be a case insensitive value of either "get" or "post".

url

The URL to which search queries should be sent. Must not be null.

getDefaultEngines()

Returns an array of all default search engines. This includes all loaded engines that aren't in the user's profile directory (NS_APP_USER_SEARCH_DIR).

void getDefaultEngines(
  [optional] out unsigned long engineCount,
  [retval, array, size_is(engineCount)] out nsISearchEngine engines
);

Parameters

engineCount

The number of default search engines.

engines

An array of the default nsISearchEngines.

getEngineByAlias()

Returns an engine with the specified alias.

nsISearchEngine getEngineByAlias(
  in AString alias
);

Parameters

alias

The search engine's alias.

Return value

An nsISearchEngine

getEngineByName()

Returns an engine with the specified name.

nsISearchEngine getEngineByName(
  in AString aEngineName
);

Parameters

aEngineName

The name of the engine.

Return value

The specified nsISearchEngine.

getEngines()

Returns an array of all installed search engines.

void getEngines(
  [optional] out unsigned long engineCount,
  [retval, array, size_is(engineCount)] out nsISearchEngine engines
);

Parameters

engineCount

The number of all installed search engines.

engines

An array of the all installed nsISearchEngines.

getVisibleEngines()

Returns an array of all installed search engines whose hidden attribute is false.

void getVisibleEngines(
  [optional] out unsigned long engineCount,
  [retval, array, size_is(engineCount)] out nsISearchEngine engines
);

Parameters

engineCount

The number of hidden installed search engines.

engines

An array of the hidden installed nsISearchEngines.

init()

Initialize the service, or if the service is already initialized, do nothing.

void init(
  [optional] in nsIBrowserSearchInitObserver observer
);

Parameters

observer

If specified, a callback called once initialization is complete, or immediately, if the service has already been initialized. In JavaScript, this observer can be a regular function.

moveEngine()

Moves a visible search engine.

void moveEngine(
  in nsISearchEngine engine,
  in long newIndex
);

Parameters

engine

The engine to move.

newIndex

The engine's new index in the set of visible engines.

Exceptions thrown

NS_ERROR_FAILURE

If newIndex is out of bounds, or if engine is hidden.

removeEngine()

Removes the search engine. If the search engine is installed in a global location, this will just hide the engine. If the engine is in the user's profile directory, it will be removed from disk.

void removeEngine(
  in nsISearchEngine engine
);

Parameters

engine

The engine to remove.

restoreDefaultEngines()

Un-hides all engines installed in the directory corresponding to the directory service's NS_APP_SEARCH_DIR key. (that is the set of engines returned by getDefaultEngines())

void restoreDefaultEngines();

Parameters

None.