nsIBrowserSearchService

Please add a summary to this article.
1.0
43
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.

Document Tags and Contributors

Tags: 
 Contributors to this page: Sheppy, Liuche, ajcrews, Yoric, trevorh
 Last updated by: Sheppy,