diff options
Diffstat (limited to 'netwerk/base/nsIBrowserSearchService.idl')
| -rw-r--r-- | netwerk/base/nsIBrowserSearchService.idl | 530 |
1 files changed, 530 insertions, 0 deletions
diff --git a/netwerk/base/nsIBrowserSearchService.idl b/netwerk/base/nsIBrowserSearchService.idl new file mode 100644 index 000000000..045973e0c --- /dev/null +++ b/netwerk/base/nsIBrowserSearchService.idl @@ -0,0 +1,530 @@ +/* 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 + * + * @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, minus the leading "www." (if present). + * 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. + * + * @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); + + /** + * 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. + * + * @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 + * 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 extensionID [optional] + * Optional: The correct extensionID if called by an add-on. + */ + void addEngineWithDetails(in AString name, + in AString iconURL, + in AString alias, + in AString description, + in AString method, + in AString url, + [optional] in AString extensionID); + + /** + * Un-hides all engines installed in the directory corresponding to + * the directory service's NS_APP_SEARCH_DIR key. (i.e. 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 + * (NS_APP_USER_SEARCH_DIR). + * + * @returns an array of nsISearchEngine objects. + */ + void getDefaultEngines( + [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"; + + + +%} |