Add m-esr52 at 52.6.0

1 files changed, 530 insertions, 0 deletions

diff --git a/netwerk/base/nsIBrowserSearchService.idl b/netwerk/base/nsIBrowserSearchService.idl
new file mode 100644
index 0000000000..045973e0c0
--- /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";
+
+
+
+%}