SearchService Reference¶

class SearchService()¶

The search service handles loading and maintaining of search engines. It will also work out the default lists for each locale/region.

SearchService.SearchService¶

SearchService._cachedSortedEngines¶

type: Array

An array of engine short names sorted into display order.

SearchService._engines¶

type: Map.<string, object>|null

A map of engine display names to SearchEngine.

SearchService._reloadingEngines¶

type: boolean

Indicates if we’re currently in maybeReloadEngines.

This is prefixed with _ rather than # because it is called in a test.

SearchService._searchDefault¶

type: object

An object containing the {id, locale} of the WebExtension for the default engine, as suggested by the configuration. For the legacy configuration, this is the user visible name.

This is prefixed with _ rather than # because it is called in a test.

SearchService.appDefaultEngine¶

SearchService.appPrivateDefaultEngine¶

SearchService.dontSetUseSavedOrder¶

type: boolean

A flag to prevent setting of useSavedOrder when there’s non-user activity happening.

SearchService.engineSelector¶

type: SearchEngineSelector|null

The engine selector singleton that is managing the engine configuration.

SearchService.errorToThrowInTest¶

type: string

Test only variable to indicate an error should occur during search service initialization.

SearchService.hasSuccessfullyInitialized¶: Determine whether initialization has been successfully completed.

SearchService.initDeferredPromise¶

type: Promise

A deferred promise that is resolved when initialization has finished.

Resolved when initalization has successfully finished, and rejected if it has failed.

SearchService.initializationStatus¶

type: string

Indicates if initialization has started, failed, succeeded or has not started yet.

These are the statuses:: “not initialized” - The SearchService has not started initialization. “started” - The SearchService has started initializaiton. “success” - The SearchService successfully completed initialization. “failed” - The SearchService failed during initialization.

SearchService.isInitialized¶

Determine whether initialization has been completed.

Clients of the service can use this attribute to quickly determine whether initialization is complete, and decide to trigger some immediate treatment, to launch asynchronous initialization or to bailout.

Note that this attribute does not indicate that initialization has succeeded, use hasSuccessfullyInitialized() for that.

SearchService.loadPathIgnoreList¶

type: Array

Various search engines may be ignored if their load path is contained in this list. The list is controlled via remote settings.

SearchService.maybeReloadDebounce¶

type: boolean

Indicates if we’re already waiting for maybeReloadEngines to be called.

SearchService.observersAdded¶

type: boolean

Keep track of observers have been added.

SearchService.openSearchUpdateTimerStarted¶

type: boolean

Keeps track to see if the OpenSearch update timer has been started or not.

SearchService.parseSubmissionMap¶

type: Map.<string, submissionMapEntry>|null

This map is built lazily after the available search engines change. It allows quick parsing of an URL representing a search submission into the search engine name and original terms.

The keys are strings containing the domain name and lowercase path of the engine submission, for example “www.google.com/search”.

SearchService.promiseInitialized¶: A promise that is resolved when initialization has finished. This does not trigger initialization to begin.

SearchService.searchPrivateDefault¶

type: object

An object containing the {id, locale} of the WebExtension for the default engine for private browsing mode, as suggested by the configuration. For the legacy configuration, this is the user visible name.

SearchService.startupExtensions¶

type: Set.<object>

A Set of installed search extensions reported by AddonManager startup before SearchSevice has started. Will be installed during init(). Does not contain application provided engines.

SearchService.startupRemovedExtensions¶

type: Set.<object>

A Set of removed search extensions reported by AddonManager startup before SearchSevice has started. Will be removed during init().

SearchService.submissionURLIgnoreList¶

type: Array

Various search engines may be ignored if their submission urls contain a string that is in the list. The list is controlled via remote settings.

SearchService._getEngineDefault(privateMode)¶

Helper function to get the current default engine.

This is prefixed with _ rather than # because it is called in test_remove_engine_notification_box.js

Arguments:

privateMode (boolean) – If true, returns the default engine for private browsing mode, otherwise the default engine for the normal mode. Note, this function does not check the “separatePrivateDefault” preference - that is up to the caller.

Returns:

nsISearchEngine|null – The appropriate search engine, or null if one could not be determined.

SearchService._makeEngineFromConfig(config, settings)¶

Create an engine object from the search configuration details.

This method is prefixed with _ rather than # because it is called in a test.

Arguments:

config (object) – The configuration object that defines the details of the engine webExtensionId etc.
settings (object) – The saved settings for the user.

Returns:

nsISearchEngine – Returns the search engine object.

SearchService._maybeReloadEngines(changeReason)¶

Reloads engines asynchronously, but only when the service has already been initialized.

This is prefixed with _ rather than # because it is called in test_reload_engines.js

Arguments:

changeReason (integer) – The reason reload engines is being called, one of Ci.nsISearchService.CHANGE_REASON*

SearchService._reloadEngines(settings, changeReason)¶

Manages reloading of the search engines when something in the user’s environment or the configuration has changed.

The order of work here is designed to avoid potential issues when updating the default engines, so that we’re not removing active defaults or trying to set a default to something that hasn’t been added yet. The order is:

Update exising engines that are in both the old and new configuration.
Add any new engines from the new configuration.
Check for changes needed to the default engines due to environment changes and potentially overriding engines as per the override allowlist.
Update the default engines.
Remove any old engines.

This is prefixed with _ rather than # because it is called in test_remove_engine_notification_box.js

Arguments:

settings (object) – The user’s current saved settings.
changeReason (integer) – The reason reload engines is being called, one of Ci.nsISearchService.CHANGE_REASON*

SearchService._showRemovalOfSearchEngineNotificationBox(prevCurrentEngineName, newCurrentEngineName)¶

Shows an infobar to notify the user their default search engine has been removed and replaced by a new default search engine.

This method is prefixed with _ rather than # because it is called in a test.

Arguments:

prevCurrentEngineName (string) – The name of the previous default engine that will be replaced.
newCurrentEngineName (string) – The name of the engine that will be the new default engine.

SearchService._sortEnginesByDefaults(engines)¶

Sorts engines by the default settings (prefs, configuration values).

Arguments:

engines (Array) – An array of engine objects to sort.

Returns:

Array – The sorted array of engine objects. This is a private method with _ rather than # because it is called in a test.

SearchService.addEnginesFromExtension(extension)¶

Called from the AddonManager when it either installs a new extension containing a search engine definition or an upgrade to an existing one.

Arguments:

extension (object) – An Extension object containing data about the extension.

SearchService.addUserEngine(name, url, alias)¶

Adds a search engine that is specified by the user.

Arguments:

name (string) – The name of the search engine
url (string) – The url that the search engine uses for searches
alias (string) – An alias for the search engine

SearchService.getEngineById(engineId)¶

Returns the engine associated with the id.

Arguments:

engineId (string) – The id of the engine.

Returns:

SearchEngine – The associated engine if found, null otherwise.

SearchService.getEngineByName(engineName)¶

If possible, please call getEngineById() rather than getEngineByName() because engines are stored as { id: object } in this._engine Map.

Returns the engine associated with the name.

Arguments:

engineName (string) – The name of the engine.

Returns:

SearchEngine – The associated engine if found, null otherwise.

SearchService.init()¶

This function calls #init to start initialization when it has not been started yet. Otherwise, it returns the pending promise.

Returns:: Promise – Returns the pending Promise when #init has started but not yet finished. | Resolved | when initialization has successfully finished. | Rejected | when initialization has failed.

SearchService.notify()¶: This is a nsITimerCallback for the timerManager notification that is registered for handling updates to search engines. Only OpenSearch engines have these updates and hence, only those are handled here.

SearchService.reset()¶: Test only - reset SearchService data. Ideally this should be replaced

SearchService.runBackgroundChecks()¶: Runs background checks for the search service. This is called from BrowserGlue and may be run once per session if the user is idle for long enough.