nsIBrowserSearchService

netwerk/base/public/nsIBrowserSearchService.idlScriptable

Please add a summary to this article.

1.0

Introduced

Gecko 1.8

Inherits from: nsISupports Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

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);

Attempting to use any method or attribute of this interface before init() has completed will force the service to fall back to a slower, synchronous, initialization. This is not an issue if your code is executed in reaction to a user interaction, as initialization is complete by then, but this is an issue if your code is executed during startup.

If you need to write code that is executed during startup and makes use of nsIBrowserSearchService, you should make sure that this code is executed from the callback to init().

Method overview

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

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

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

nsISearchEngine getEngineByAlias(in AString alias);

nsISearchEngine getEngineByName(in AString aEngineName);

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

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

void init([optional] in nsIBrowserSearchInitObserver observer);

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

void removeEngine(in nsISearchEngine engine);

void restoreDefaultEngines();

Attributes

Attribute	Type	Description
`currentEngine`	`nsISearchEngine`	The currently active search engine. May be `null` if there are no visible search engines.
`defaultEngine`	`nsISearchEngine`	The default search engine. Returns the first visible engine if the default engine is hidden. May be `null` if there are no visible search engines. Read only.
`originalDefaultEngine`	`nsISearchEngine`	The original default engine. This differs from the "`defaultEngine`" attribute in that it always returns a given build's default engine, regardless of whether it is hidden. Read only.

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.

This method was introduced in Firefox 16.

Attempting to call any method of this interface before init() has completed will force the service to fall back to a slower, synchronous, initialization.

If your code requires nsIBrowserSearchService and is executed during startup, you should make sure that this code is executed from the callback to init().

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.