forked from mirrors/gecko-dev
093e6d0259
MozReview-Commit-ID: 1mfqU6mOyR9 --HG-- extra : rebase_source : 0750532c3e7cc1a3488387091afbfb68279a46b8
563 lines
19 KiB
Text
563 lines
19 KiB
Text
/* This Source Code Form is subject to the terms of the Mozilla Public
|
|
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
|
|
|
|
#include "nsISupports.idl"
|
|
|
|
interface nsIURI;
|
|
interface nsIInputStream;
|
|
|
|
[scriptable, uuid(5799251f-5b55-4df7-a9e7-0c27812c469a)]
|
|
interface nsISearchSubmission : nsISupports
|
|
{
|
|
/**
|
|
* The POST data associated with a search submission, wrapped in a MIME
|
|
* input stream. May be null.
|
|
*/
|
|
readonly attribute nsIInputStream postData;
|
|
|
|
/**
|
|
* The URI to submit a search to.
|
|
*/
|
|
readonly attribute nsIURI uri;
|
|
};
|
|
|
|
[scriptable, uuid(620bd920-0491-48c8-99a8-d6047e64802d)]
|
|
interface nsISearchEngine : nsISupports
|
|
{
|
|
/**
|
|
* Gets a nsISearchSubmission object that contains information about what to
|
|
* send to the search engine, including the URI and postData, if applicable.
|
|
*
|
|
* @param data
|
|
* Data to add to the submission object.
|
|
* i.e. the search terms.
|
|
*
|
|
* @param responseType [optional]
|
|
* The MIME type that we'd like to receive in response
|
|
* to this submission. If null, will default to "text/html".
|
|
*
|
|
* @param 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.
|
|
*
|
|
* @returns A nsISearchSubmission object that contains information about what
|
|
* to send to the search engine. If no submission can be
|
|
* obtained for the given responseType, returns null.
|
|
*/
|
|
nsISearchSubmission getSubmission(in AString data,
|
|
[optional] in AString responseType,
|
|
[optional] in AString purpose);
|
|
|
|
/**
|
|
* Adds a parameter to the search engine's submission data. This should only
|
|
* be called on engines created via addEngineWithDetails.
|
|
*
|
|
* @param name
|
|
* The parameter's name. Must not be null.
|
|
*
|
|
* @param 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.
|
|
*
|
|
* @param 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"
|
|
*
|
|
* @throws NS_ERROR_FAILURE if the search engine is read-only.
|
|
* @throws NS_ERROR_INVALID_ARG if name or value are null.
|
|
*/
|
|
void addParam(in AString name, in AString value, in AString responseType);
|
|
|
|
/**
|
|
* Determines whether the engine can return responses in the given
|
|
* MIME type. Returns true if the engine spec has a URL with the
|
|
* given responseType, false otherwise.
|
|
*
|
|
* @param responseType
|
|
* The MIME type to check for
|
|
*/
|
|
boolean supportsResponseType(in AString responseType);
|
|
|
|
/**
|
|
* Returns a string with the URL to an engine's icon matching both width and
|
|
* height. Returns null if icon with specified dimensions is not found.
|
|
*
|
|
* @param width
|
|
* Width of the requested icon.
|
|
* @param height
|
|
* Height of the requested icon.
|
|
*/
|
|
AString getIconURLBySize(in long width, in long height);
|
|
|
|
/**
|
|
* Gets an array of all available icons. Each entry is an object with
|
|
* width, height and url properties. width and height are numeric and
|
|
* represent the icon's dimensions. url is a string with the URL for
|
|
* the icon.
|
|
*/
|
|
jsval getIcons();
|
|
|
|
/**
|
|
* Opens a speculative connection to the engine's search URI
|
|
* (and suggest URI, if different) to reduce request latency
|
|
*
|
|
* @param options
|
|
* An object that must contain the following fields:
|
|
* {window} the content window for the window performing the search
|
|
* {originAttributes} the originAttributes for performing the search
|
|
*
|
|
* @throws NS_ERROR_INVALID_ARG if options is omitted or lacks required
|
|
* elemeents
|
|
*/
|
|
void speculativeConnect(in jsval options);
|
|
|
|
/**
|
|
* An optional shortcut alias for the engine.
|
|
* When non-null, this is a unique identifier.
|
|
*/
|
|
attribute AString alias;
|
|
|
|
/**
|
|
* A text description describing the engine.
|
|
*/
|
|
readonly attribute AString description;
|
|
|
|
/**
|
|
* Whether the engine should be hidden from the user.
|
|
*/
|
|
attribute boolean hidden;
|
|
|
|
/**
|
|
* A nsIURI corresponding to the engine's icon, stored locally. May be null.
|
|
*/
|
|
readonly attribute nsIURI iconURI;
|
|
|
|
/**
|
|
* The display name of the search engine. This is a unique identifier.
|
|
*/
|
|
readonly attribute AString name;
|
|
|
|
/**
|
|
* A URL string pointing to the engine's search form.
|
|
*/
|
|
readonly attribute AString searchForm;
|
|
|
|
/**
|
|
* An optional unique identifier for this search engine within the context of
|
|
* the distribution, as provided by the distributing entity.
|
|
*/
|
|
readonly attribute AString identifier;
|
|
|
|
/**
|
|
* Gets a string representing the hostname from which search results for a
|
|
* given responseType are returned. This can be specified as an url attribute
|
|
* in the engine description file, but will default to host from the <Url>'s
|
|
* template otherwise.
|
|
*
|
|
* @param responseType [optional]
|
|
* The MIME type to get resultDomain for. Defaults to "text/html".
|
|
*
|
|
* @return the resultDomain for the given responseType.
|
|
*/
|
|
AString getResultDomain([optional] in AString responseType);
|
|
};
|
|
|
|
[scriptable, uuid(0dc93e51-a7bf-4a16-862d-4b3469ff6206)]
|
|
interface nsISearchParseSubmissionResult : nsISupports
|
|
{
|
|
/**
|
|
* The search engine associated with the URL passed in to
|
|
* nsISearchEngine::parseSubmissionURL, or null if the URL does not represent
|
|
* a search submission.
|
|
*/
|
|
readonly attribute nsISearchEngine engine;
|
|
|
|
/**
|
|
* String containing the sought terms. This can be an empty string in case no
|
|
* terms were specified or the URL does not represent a search submission.
|
|
*/
|
|
readonly attribute AString terms;
|
|
|
|
/**
|
|
* The offset of the string |terms| in the URL passed in to
|
|
* nsISearchEngine::parseSubmissionURL, or -1 if the URL does not represent
|
|
* a search submission.
|
|
*/
|
|
readonly attribute long termsOffset;
|
|
|
|
/**
|
|
* The length of the |terms| in the original encoding of the URL passed in to
|
|
* nsISearchEngine::parseSubmissionURL. If the search term in the original
|
|
* URL is encoded then this will be bigger than |terms.length|.
|
|
*/
|
|
readonly attribute long termsLength;
|
|
};
|
|
|
|
[scriptable, uuid(9fc39136-f08b-46d3-b232-96f4b7b0e235)]
|
|
interface nsISearchInstallCallback : nsISupports
|
|
{
|
|
const unsigned long ERROR_UNKNOWN_FAILURE = 0x1;
|
|
const unsigned long ERROR_DUPLICATE_ENGINE = 0x2;
|
|
|
|
/**
|
|
* Called to indicate that the engine addition process succeeded.
|
|
*
|
|
* @param engine
|
|
* The nsISearchEngine object that was added (will not be null).
|
|
*/
|
|
void onSuccess(in nsISearchEngine engine);
|
|
|
|
/**
|
|
* Called to indicate that the engine addition process failed.
|
|
*
|
|
* @param errorCode
|
|
* One of the ERROR_* values described above indicating the cause of
|
|
* the failure.
|
|
*/
|
|
void onError(in unsigned long errorCode);
|
|
};
|
|
|
|
/**
|
|
* Callback for asynchronous initialization of nsIBrowserSearchService
|
|
*/
|
|
[scriptable, function, uuid(02256156-16e4-47f1-9979-76ff98ceb590)]
|
|
interface nsIBrowserSearchInitObserver : nsISupports
|
|
{
|
|
/**
|
|
* Called once initialization of the browser search service is complete.
|
|
*
|
|
* @param aStatus The status of that service.
|
|
*/
|
|
void onInitComplete(in nsresult aStatus);
|
|
};
|
|
|
|
[scriptable, uuid(150ef720-bbe2-4169-b9f3-ef7ec0654ced)]
|
|
interface nsIBrowserSearchService : nsISupports
|
|
{
|
|
/**
|
|
* Start asynchronous initialization.
|
|
*
|
|
* The callback is triggered once initialization is complete, which may be
|
|
* immediately, if initialization has already been completed by some previous
|
|
* call to this method. The callback is always invoked asynchronously.
|
|
*
|
|
* @param aObserver An optional object observing the end of initialization.
|
|
*/
|
|
void init([optional] in nsIBrowserSearchInitObserver aObserver);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @return |true| if the search service is now initialized, |false| if
|
|
* initialization has not been triggered yet.
|
|
*/
|
|
readonly attribute bool isInitialized;
|
|
|
|
/**
|
|
* Resets the default engine to its original value.
|
|
*/
|
|
void resetToOriginalDefaultEngine();
|
|
|
|
/**
|
|
* Checks if an EngineURL of type URLTYPE_SEARCH_HTML exists for
|
|
* any engine, with a matching method, template URL, and query params.
|
|
*
|
|
* @param method
|
|
* The HTTP request method used when submitting a search query.
|
|
* Must be a case insensitive value of either "get" or "post".
|
|
*
|
|
* @param url
|
|
* The URL to which search queries should be sent.
|
|
* Must not be null.
|
|
*
|
|
* @param formData
|
|
* The un-sorted form data used as query params.
|
|
*/
|
|
boolean hasEngineWithURL(in AString method, in AString url, in jsval formData);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param engineURL
|
|
* The URL to the search engine's description file.
|
|
*
|
|
* @param dataType
|
|
* Obsolete, the value is ignored.
|
|
*
|
|
* @param 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.
|
|
*
|
|
* @param 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.
|
|
*
|
|
* @param 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.
|
|
*
|
|
* @param extensionID [optional]
|
|
* Optional: The correct extensionID if called by an add-on.
|
|
*
|
|
* @throws NS_ERROR_FAILURE if the description file cannot be successfully
|
|
* loaded.
|
|
*/
|
|
void addEngine(in AString engineURL, in long dataType, in AString iconURL,
|
|
in boolean confirm, [optional] in nsISearchInstallCallback callback,
|
|
[optional] in AString extensionID);
|
|
|
|
/**
|
|
* Adds a new search engine, without asking the user for confirmation and
|
|
* without starting to use it right away.
|
|
*
|
|
* @param name
|
|
* The search engine's name. Must be unique. Must not be null.
|
|
*
|
|
* @param iconURL
|
|
* Optional: A URL string pointing to the icon to be used to represent
|
|
* the engine.
|
|
* This is a jsval so that an object can be passed to replace the
|
|
* parameters below.
|
|
*
|
|
* @param alias
|
|
* Optional: A unique shortcut that can be used to retrieve the
|
|
* search engine.
|
|
*
|
|
* @param description
|
|
* Optional: a description of the search engine.
|
|
*
|
|
* @param method
|
|
* Optional: The HTTP request method used when submitting a search query.
|
|
* Case insensitive value of either "get" or "post".
|
|
* Defaults to "get".
|
|
*
|
|
* @param template
|
|
* The template for the URL to which search queries should be sent. The
|
|
* template will be subjected to OpenSearch parameter substitution.
|
|
* See http://www.opensearch.org/Specifications/OpenSearch
|
|
* Must not be null.
|
|
*
|
|
* @param extensionID [optional]
|
|
* Optional: The correct extensionID if called by an add-on.
|
|
*
|
|
* Alternatively, all of these parameters except for name can be
|
|
* passed as an object in place of parameter two.
|
|
*
|
|
* Services.search.addEngineWithDetails("Example engine", {
|
|
* template: "http://example.com/?search={searchTerms}",
|
|
* description: "Example search engine description",
|
|
* suggestURL: http://example.com/?suggest={searchTerms},
|
|
* });
|
|
*
|
|
* Using this method, you can use a new parameter, suggestURL:
|
|
*
|
|
* @param suggestURL [optional]
|
|
* Optional: The URL to which search suggestion requests
|
|
* should be sent.
|
|
*
|
|
*/
|
|
void addEngineWithDetails(in AString name,
|
|
in jsval iconURL,
|
|
[optional] in AString alias,
|
|
[optional] in AString description,
|
|
[optional] in AString method,
|
|
[optional] in AString url,
|
|
[optional] in AString extensionID);
|
|
|
|
/**
|
|
* Un-hides all engines in the set of engines returned by getDefaultEngines.
|
|
*/
|
|
void restoreDefaultEngines();
|
|
|
|
/**
|
|
* Returns an engine with the specified alias.
|
|
*
|
|
* @param alias
|
|
* The search engine's alias.
|
|
* @returns The corresponding nsISearchEngine object, or null if it doesn't
|
|
* exist.
|
|
*/
|
|
nsISearchEngine getEngineByAlias(in AString alias);
|
|
|
|
/**
|
|
* Returns an engine with the specified name.
|
|
*
|
|
* @param aEngineName
|
|
* The name of the engine.
|
|
* @returns The corresponding nsISearchEngine object, or null if it doesn't
|
|
* exist.
|
|
*/
|
|
nsISearchEngine getEngineByName(in AString aEngineName);
|
|
|
|
/**
|
|
* Returns an array of all installed search engines.
|
|
*
|
|
* @returns an array of nsISearchEngine objects.
|
|
*/
|
|
void getEngines(
|
|
[optional] out unsigned long engineCount,
|
|
[retval, array, size_is(engineCount)] out nsISearchEngine engines);
|
|
|
|
/**
|
|
* Returns an array of all installed search engines whose hidden attribute is
|
|
* false.
|
|
*
|
|
* @returns an array of nsISearchEngine objects.
|
|
*/
|
|
void getVisibleEngines(
|
|
[optional] out unsigned long engineCount,
|
|
[retval, array, size_is(engineCount)] out nsISearchEngine engines);
|
|
|
|
/**
|
|
* Returns an array of all default search engines. This includes all loaded
|
|
* engines that aren't in the user's profile directory.
|
|
*
|
|
* @returns an array of nsISearchEngine objects.
|
|
*/
|
|
void getDefaultEngines(
|
|
[optional] out unsigned long engineCount,
|
|
[retval, array, size_is(engineCount)] out nsISearchEngine engines);
|
|
|
|
/**
|
|
* Returns an array of search engines installed by a given extension.
|
|
*
|
|
* @returns an array of nsISearchEngine objects.
|
|
*/
|
|
void getEnginesByExtensionID(in AString extensionID,
|
|
[optional] out unsigned long engineCount,
|
|
[retval, array, size_is(engineCount)] out nsISearchEngine engines);
|
|
|
|
|
|
/**
|
|
* Moves a visible search engine.
|
|
*
|
|
* @param engine
|
|
* The engine to move.
|
|
* @param newIndex
|
|
* The engine's new index in the set of visible engines.
|
|
*
|
|
* @throws NS_ERROR_FAILURE if newIndex is out of bounds, or if engine is
|
|
* hidden.
|
|
*/
|
|
void moveEngine(in nsISearchEngine engine, in long newIndex);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param engine
|
|
* The engine to remove.
|
|
*/
|
|
void removeEngine(in nsISearchEngine engine);
|
|
|
|
/**
|
|
* The original Engine object that is the default for this region,
|
|
* ignoring changes the user may have subsequently made.
|
|
*/
|
|
readonly attribute nsISearchEngine originalDefaultEngine;
|
|
|
|
/**
|
|
* Alias for the currentEngine attribute, kept for add-on compatibility.
|
|
*/
|
|
attribute nsISearchEngine defaultEngine;
|
|
|
|
/**
|
|
* 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 original default engine if it's not hidden, then to
|
|
* the first visible engine, and as a last resort it will unhide the original
|
|
* default engine.
|
|
*/
|
|
attribute nsISearchEngine currentEngine;
|
|
|
|
/**
|
|
* Gets a representation of the default engine in an anonymized JSON
|
|
* string suitable for recording in the Telemetry environment.
|
|
*
|
|
* @return an object containing anonymized info about the default engine:
|
|
* name, loadPath, submissionURL (for default engines).
|
|
*/
|
|
jsval getDefaultEngineInfo();
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param url
|
|
* String containing the URL to parse, for example
|
|
* "https://www.google.com/search?q=terms".
|
|
*/
|
|
nsISearchParseSubmissionResult parseSubmissionURL(in AString url);
|
|
};
|
|
|
|
%{ C++
|
|
/**
|
|
* The observer topic to listen to for actions performed on installed
|
|
* search engines.
|
|
*/
|
|
#define SEARCH_ENGINE_TOPIC "browser-search-engine-modified"
|
|
|
|
/**
|
|
* Sent when an engine is removed from the data store.
|
|
*/
|
|
#define SEARCH_ENGINE_REMOVED "engine-removed"
|
|
|
|
/**
|
|
* Sent when an engine is changed. This includes when the engine's "hidden"
|
|
* property is changed.
|
|
*/
|
|
#define SEARCH_ENGINE_CHANGED "engine-changed"
|
|
|
|
/**
|
|
* Sent when an engine is added to the list of available engines.
|
|
*/
|
|
#define SEARCH_ENGINE_ADDED "engine-added"
|
|
|
|
/**
|
|
* Sent when a search engine being installed from a remote plugin description
|
|
* file is completely loaded. This is used internally by the search service as
|
|
* an indication of when the engine can be added to the internal store, and
|
|
* therefore should not be used to detect engine availability. It is always
|
|
* followed by an "added" notification.
|
|
*/
|
|
#define SEARCH_ENGINE_LOADED "engine-loaded"
|
|
|
|
/**
|
|
* Sent when the "current" engine is changed.
|
|
*/
|
|
#define SEARCH_ENGINE_CURRENT "engine-current";
|
|
|
|
/**
|
|
* Sent when the "default" engine is changed.
|
|
*/
|
|
#define SEARCH_ENGINE_DEFAULT "engine-default";
|
|
|
|
|
|
|
|
%}
|