nsISearchEngine

Please add a summary to this article.
Last changed in Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

Inherits from: nsISupports

Method overview

void addParam(in AString name, in AString value, in AString responseType);
nsISearchSubmission getSubmission(in AString data, [optional] in AString responseType, [optional] in AString purpose);
boolean supportsResponseType(in AString responseType);

Attributes

Attribute Type Description
alias AString An optional shortcut alias for the engine. When non-null, this is a unique identifier.
description AString A text description describing the engine. Read only.
hidden boolean Whether the engine should be hidden from the user.
iconURI nsIURI A nsIURI corresponding to the engine's icon, stored locally. May be null. Read only.
name AString The display name of the search engine. This is a unique identifier. Read only.
searchForm AString A URL string pointing to the engine's search form. Read only.
type long The search engine type. Read only.

Constants

Search engine type constants

Constant Value Description
TYPE_MOZSEARCH 1
TYPE_SHERLOCK 2
TYPE_OPENSEARCH 3

Search engine data type constants

Constant Value Description
DATA_XML 1 Data type is XML
DATA_TEXT 2 Data type is Text.

Methods

addParam()

Adds a parameter to the search engine's submission data. This should only be called on engines created via nsIBrowserSearchService.addEngineWithDetails().

void addParam(
  in AString name,
  in AString value,
  in AString responseType
);
Parameters
name
The name of the parameter to add.
value
The value to pass. If value is "{searchTerms}", it will be substituted with the user-entered data when retrieving the submission. Must not be null.
responseType
Since an engine can have several different request URLs, differentiated by response types, this parameter selects a request to add parameters to. If null, will default to "text/html"
Exceptions thrown
NS_ERROR_INVALID_ARG
If name or value are null.
NS_ERROR_FAILURE
If the search engine is read-only.

getSubmission()

Gets a nsISearchSubmission object that contains information about what to send to the search engine, including the URI and postData, if applicable.

nsISearchSubmission getSubmission(
  in AString data,
  [optional] in AString responseType,
  [optional] in AString purpose
);
Parameters
data
Data to add to the submission object. That is the search terms.
responseType
[optional] The MIME type that we'd like to receive in response to this submission. If null, will default to "text/html".
purpose
[optional] A string meant to indicate the context of the search request. This allows the search service to provide a different nsISearchSubmission depending on e.g. where the search is triggered in the UI. Possible values depend on the application's installed search engines.
Return value

An nsISearchSubmission

supportsResponseType()

Determines whether the engine can return responses in the given MIME type.

boolean supportsResponseType(
  in AString responseType
);
Parameters
responseType
The MIME type to check for.
Return value

Returns true if the engine spec has a URL with the given responseType, false otherwise.

See also