Interface nsISearchServiceType

Hierarchy

Properties

appDefaultEngine appPrivateDefaultEngine defaultEngine defaultPrivateEngine isInitialized separatePrivateDefaultUrlbarResultEnabled

Methods

AddRef QueryInterface Release addEnginesFromExtension addOpenSearchEngine addUserEngine getAppProvidedEngines getDefault getDefaultEngineInfo getDefaultPrivate getEngineByAlias getEngineById getEngineByName getEngines getEnginesByExtensionID getVisibleEngines init maybeSetAndOverrideDefault moveEngine parseSubmissionURL removeEngine removeWebExtensionEngine resetToAppDefaultEngine restoreDefaultEngines runBackgroundChecks setDefault setDefaultPrivate

Properties

Readonly appDefaultEngine

appDefaultEngine: nsISearchEngine

The Application Default Engine object that is the default for this region, ignoring changes the user may have subsequently made.

Readonly appPrivateDefaultEngine

appPrivateDefaultEngine: nsISearchEngine

The Application Default Engine object that is the default for this region when in private browsing mode, ignoring changes the user may have subsequently made.

defaultEngine

defaultEngine: nsISearchEngine

The currently active search engine. Unless the application doesn't ship any search plugin, this should never be null. If the currently active engine is removed, this attribute will fallback first to the application default engine if it's not hidden, then to the first visible engine, and as a last resort it will unhide the app default engine.

defaultPrivateEngine

defaultPrivateEngine: nsISearchEngine

The currently active search engine for private browsing mode.

See

defaultEngine.

Readonly isInitialized

isInitialized: bool

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.

Returns

|true| if the search service is now initialized, |false| if initialization has not been triggered yet.

Readonly separatePrivateDefaultUrlbarResultEnabled

separatePrivateDefaultUrlbarResultEnabled: boolean

Whether to display the "Search in Private Window" result in the urlbar.

Methods

AddRef

  • Increases the reference count for this interface. The associated instance will not be deleted unless the reference count is returned to zero.

    Returns

    The resulting reference count.

    Returns number

QueryInterface

  • Parameters

    • aIID: object
    • Optional aInstancePtr: object

    Returns any

  • A run time mechanism for interface discovery.

    Returns

    NS_OK if the interface is supported by the associated instance, NS_NOINTERFACE if it is not.

    aInstancePtr must not be null.

    Parameters

    • aIID: object

      [in] A requested interface IID

    • aInstancePtr: object

      [out] A pointer to an interface pointer to receive the result.

    Returns void

Release

  • Decreases the reference count for this interface. Generally, if the reference count returns to zero, the associated instance is deleted.

    Returns

    The resulting reference count.

    Returns number

addEnginesFromExtension

  • Adds search providers to the search service. If the search service is configured to load multiple locales for the extension, it may load more than one search engine. If called directly ensure the extension has been initialised.

    Returns

    Promise that resolves when finished.

    Parameters

    • extension: any

      The extension to load from.

    Returns any

addOpenSearchEngine

  • Adds a new Open Search engine from the file at the supplied URI.

    Throws

    NS_ERROR_FAILURE if the description file cannot be successfully loaded.

    Parameters

    • engineURL: string

      The URL to the search engine's description file.

    • iconURL: string

      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.

    Returns any

addUserEngine

  • Adds a new search engine defined by the user.

    Parameters

    • name: string

      The name of the engine.

    • url: string

      The url of the engine with %s denoting where to replace the search term.

    • alias: string

      [optional] The alias to refer to the engine.

    Returns any

getAppProvidedEngines

  • Returns an array of all default search engines. This includes all loaded engines that aren't in the user's profile directory. The array is sorted to the default order.

    Returns

    an array of nsISearchEngine objects.

    Returns any

getDefault

  • Returns any

getDefaultEngineInfo

  • Gets a representation of the default engine in an anonymized JSON string suitable for recording in the Telemetry environment.

    Returns

    result contains anonymized info about the default engine(s).

    Returns

    result.defaultSearchEngine contains the telemetry id of the default engine.

    Returns

    result.defaultSearchEngineData contains information about the default engine: name, loadPath, original submissionURL

    Returns

    [result.defaultPrivateSearchEngine] only returned if the preference for having a separate engine in private mode is turned on. contains the telemetry id of the default engine for private browsing mode.

    Returns

    [result.defaultPrivateSearchEngineData] only returned if the preference for having a separate engine in private mode is turned on. contains information about the default engine for private browsing mode: name, loadPath, original submissionURL

    Returns any

getDefaultPrivate

  • Returns any

getEngineByAlias

  • Returns an engine with the specified alias.

    Returns

    The corresponding nsISearchEngine object, or null if it doesn't exist.

    Parameters

    • alias: string

      The search engine's alias.

    Returns any

getEngineById

  • Returns an engine with the specified Id.

    Returns

    The corresponding nsISearchEngine object, or null if it doesn't exist.

    Parameters

    • aEngineId: string

      The Id of the engine.

    Returns nsISearchEngine

getEngineByName

  • Returns an engine with the specified name.

    Returns

    The corresponding nsISearchEngine object, or null if it doesn't exist.

    Parameters

    • aEngineName: string

      The name of the engine.

    Returns nsISearchEngine

getEngines

  • Returns an array of all installed search engines. The array is sorted either to the user requirements or the default order.

    Returns

    an array of nsISearchEngine objects.

    Returns any

getEnginesByExtensionID

  • Returns an array of search engines installed by a given extension.

    Returns

    an array of nsISearchEngine objects.

    Parameters

    • extensionID: string

    Returns any

getVisibleEngines

  • Returns an array of all installed search engines whose hidden attribute is false. The array is sorted either to the user requirements or the default order.

    Returns

    an array of nsISearchEngine objects.

    Returns any

init

  • Start asynchronous initialization.

    The promise is resolved once initialization is complete, which may be immediately, if initialization has already been completed by some previous call to this method. This method should only be called when you need or want to wait for the full initialization of the search service.

    Returns any

maybeSetAndOverrideDefault

  • Allows the add-on manager to discover if a WebExtension based search engine may change the default to an application provided search engine. If that WebExtension is on the allow list, then it will override the built-in engine's urls and parameters.

    Returns

    An object with two booleans:

    • canChangeToAppProvided: indicates if the WebExtension engine may set the named engine as default e.g. it is application provided.
    • canInstallEngine: indicates if the WebExtension engine may be installed, e.g. it is not an app-provided engine.

    Parameters

    • extension: any

      The extension to load from.

    Returns any

moveEngine

  • Moves a visible search engine.

    Throws

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

    Parameters

    • engine: nsISearchEngine

      The engine to move.

    • newIndex: number

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

    Returns any

parseSubmissionURL

  • Determines if the provided URL represents results from a search engine, and provides details about the match.

    The lookup mechanism checks whether the domain name and path of the provided HTTP or HTTPS URL matches one of the known values for the visible search engines. The match does not depend on which of the schemes is used. The expected URI parameter for the search terms must exist in the query string, but other parameters are ignored.

    Parameters

    Returns nsISearchParseSubmissionResult

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.

    Parameters

    • engine: nsISearchEngine

      The engine to remove.

    Returns any

removeWebExtensionEngine

  • Notify nsSearchService that an extension has been removed. Removes any engines that are associated with that extension.

    Parameters

    • id: string

      The id of the extension.

    Returns any

resetToAppDefaultEngine

  • Resets the default engine to its app default engine value.

    Returns any

restoreDefaultEngines

  • Un-hides all engines in the set of engines returned by getAppProvidedEngines.

    Returns void

runBackgroundChecks

  • Runs background checks; Designed to be run on idle.

    Returns any

setDefault

  • Parameters

    • engine: nsISearchEngine
    • changeSource: number

    Returns any

setDefaultPrivate

  • Parameters

    • engine: nsISearchEngine
    • changeSource: number

    Returns any

Settings

Member Visibility

Theme

Generated using TypeDoc