michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIURI;
michael@0: interface nsIInputStream;
michael@0: 
michael@0: [scriptable, uuid(5799251f-5b55-4df7-a9e7-0c27812c469a)]
michael@0: interface nsISearchSubmission : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * The POST data associated with a search submission, wrapped in a MIME
michael@0:    * input stream. May be null.
michael@0:    */
michael@0:   readonly attribute nsIInputStream postData;
michael@0: 
michael@0:   /**
michael@0:    * The URI to submit a search to.
michael@0:    */
michael@0:   readonly attribute nsIURI uri;
michael@0: };
michael@0: 
michael@0: [scriptable, uuid(77de6680-57ec-4105-a183-cc7cf7e84b09)]
michael@0: interface nsISearchEngine : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Gets a nsISearchSubmission object that contains information about what to
michael@0:    * send to the search engine, including the URI and postData, if applicable.
michael@0:    *
michael@0:    * @param  data
michael@0:    *         Data to add to the submission object.
michael@0:    *         i.e. the search terms.
michael@0:    *
michael@0:    * @param  responseType [optional]
michael@0:    *         The MIME type that we'd like to receive in response
michael@0:    *         to this submission.  If null, will default to "text/html".
michael@0:    *
michael@0:    * @param purpose [optional]
michael@0:    *        A string meant to indicate the context of the search request. This
michael@0:    *        allows the search service to provide a different nsISearchSubmission
michael@0:    *        depending on e.g. where the search is triggered in the UI.
michael@0:    *
michael@0:    * @returns A nsISearchSubmission object that contains information about what
michael@0:    *          to send to the search engine.  If no submission can be
michael@0:    *          obtained for the given responseType, returns null.
michael@0:    */
michael@0:   nsISearchSubmission getSubmission(in AString data,
michael@0:                                     [optional] in AString responseType,
michael@0:                                     [optional] in AString purpose);
michael@0: 
michael@0:   /**
michael@0:    * Adds a parameter to the search engine's submission data. This should only
michael@0:    * be called on engines created via addEngineWithDetails.
michael@0:    *
michael@0:    * @param name
michael@0:    *        The parameter's name. Must not be null.
michael@0:    *
michael@0:    * @param value
michael@0:    *        The value to pass. If value is "{searchTerms}", it will be
michael@0:    *        substituted with the user-entered data when retrieving the
michael@0:    *        submission. Must not be null.
michael@0:    *
michael@0:    * @param responseType
michael@0:    *        Since an engine can have several different request URLs,
michael@0:    *        differentiated by response types, this parameter selects
michael@0:    *        a request to add parameters to.  If null, will default
michael@0:    *        to "text/html"
michael@0:    *
michael@0:    * @throws NS_ERROR_FAILURE if the search engine is read-only.
michael@0:    * @throws NS_ERROR_INVALID_ARG if name or value are null.
michael@0:    */
michael@0:   void addParam(in AString name, in AString value, in AString responseType);
michael@0: 
michael@0:   /**
michael@0:    * Determines whether the engine can return responses in the given
michael@0:    * MIME type.  Returns true if the engine spec has a URL with the
michael@0:    * given responseType, false otherwise.
michael@0:    *
michael@0:    * @param responseType
michael@0:    *        The MIME type to check for
michael@0:    */
michael@0:   boolean supportsResponseType(in AString responseType);
michael@0: 
michael@0:   /**
michael@0:    * Returns a string with the URL to an engine's icon matching both width and
michael@0:    * height. Returns null if icon with specified dimensions is not found.
michael@0:    *
michael@0:    * @param width
michael@0:    *        Width of the requested icon.
michael@0:    * @param height
michael@0:    *        Height of the requested icon.
michael@0:    */
michael@0:   AString getIconURLBySize(in long width, in long height);
michael@0: 
michael@0:   /**
michael@0:    * Gets an array of all available icons. Each entry is an object with
michael@0:    * width, height and url properties. width and height are numeric and
michael@0:    * represent the icon's dimensions. url is a string with the URL for
michael@0:    * the icon.
michael@0:    */
michael@0:   jsval getIcons();
michael@0: 
michael@0:   /**
michael@0:    * Supported search engine types.
michael@0:    */
michael@0:   const unsigned long TYPE_MOZSEARCH     = 1;
michael@0:   const unsigned long TYPE_SHERLOCK      = 2;
michael@0:   const unsigned long TYPE_OPENSEARCH    = 3;
michael@0: 
michael@0:   /**
michael@0:    * Supported search engine data types.
michael@0:    */
michael@0:   const unsigned long DATA_XML     = 1;
michael@0:   const unsigned long DATA_TEXT    = 2;
michael@0: 
michael@0:   /**
michael@0:    * An optional shortcut alias for the engine.
michael@0:    * When non-null, this is a unique identifier.
michael@0:    */
michael@0:   attribute AString alias;
michael@0: 
michael@0:   /**
michael@0:    * A text description describing the engine.
michael@0:    */
michael@0:   readonly attribute AString description;
michael@0: 
michael@0:   /**
michael@0:    * Whether the engine should be hidden from the user.
michael@0:    */
michael@0:   attribute boolean hidden;
michael@0: 
michael@0:   /**
michael@0:    * A nsIURI corresponding to the engine's icon, stored locally. May be null.
michael@0:    */
michael@0:   readonly attribute nsIURI iconURI;
michael@0: 
michael@0:   /**
michael@0:    * The display name of the search engine. This is a unique identifier.
michael@0:    */
michael@0:   readonly attribute AString name;
michael@0: 
michael@0:   /**
michael@0:    * A URL string pointing to the engine's search form.
michael@0:    */
michael@0:   readonly attribute AString searchForm;
michael@0: 
michael@0:   /**
michael@0:    * The search engine type.
michael@0:    */
michael@0:   readonly attribute long type;
michael@0: 
michael@0:   /**
michael@0:    * An optional unique identifier for this search engine within the context of
michael@0:    * the distribution, as provided by the distributing entity.
michael@0:    */
michael@0:   readonly attribute AString identifier;
michael@0: 
michael@0:   /**
michael@0:    * Gets a string representing the hostname from which search results for a
michael@0:    * given responseType are returned, minus the leading "www." (if present).
michael@0:    * This can be specified as an url attribute in the engine description file,
michael@0:    * but will default to host from the <Url>'s template otherwise.
michael@0:    *
michael@0:    * @param  responseType [optional]
michael@0:    *         The MIME type to get resultDomain for.  Defaults to "text/html".
michael@0:    *
michael@0:    * @return the resultDomain for the given responseType.
michael@0:    */
michael@0:   AString getResultDomain([optional] in AString responseType);
michael@0: };
michael@0: 
michael@0: [scriptable, uuid(9fc39136-f08b-46d3-b232-96f4b7b0e235)]
michael@0: interface nsISearchInstallCallback : nsISupports
michael@0: {
michael@0:   const unsigned long ERROR_UNKNOWN_FAILURE = 0x1;
michael@0:   const unsigned long ERROR_DUPLICATE_ENGINE = 0x2;
michael@0: 
michael@0:   /**
michael@0:    * Called to indicate that the engine addition process succeeded.
michael@0:    *
michael@0:    * @param engine
michael@0:    *        The nsISearchEngine object that was added (will not be null).
michael@0:    */
michael@0:   void onSuccess(in nsISearchEngine engine);
michael@0: 
michael@0:   /**
michael@0:    * Called to indicate that the engine addition process failed.
michael@0:    *
michael@0:    * @param errorCode
michael@0:    *        One of the ERROR_* values described above indicating the cause of
michael@0:    *        the failure.
michael@0:    */
michael@0:   void onError(in unsigned long errorCode);
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * Callback for asynchronous initialization of nsIBrowserSearchService
michael@0:  */
michael@0: [scriptable, function, uuid(02256156-16e4-47f1-9979-76ff98ceb590)]
michael@0: interface nsIBrowserSearchInitObserver : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Called once initialization of the browser search service is complete.
michael@0:    *
michael@0:    * @param aStatus The status of that service.
michael@0:    */
michael@0:   void onInitComplete(in nsresult aStatus);
michael@0: };
michael@0: 
michael@0: [scriptable, uuid(939d74a4-5b01-463c-80c7-4301f0c0f9ef)]
michael@0: interface nsIBrowserSearchService : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Start asynchronous initialization.
michael@0:    *
michael@0:    * The callback is triggered once initialization is complete, which may be
michael@0:    * immediately, if initialization has already been completed by some previous
michael@0:    * call to this method. The callback is always invoked asynchronously.
michael@0:    *
michael@0:    * @param aObserver An optional object observing the end of initialization.
michael@0:    */
michael@0:   void init([optional] in nsIBrowserSearchInitObserver aObserver);
michael@0: 
michael@0:   /**
michael@0:    * Determine whether initialization has been completed.
michael@0:    *
michael@0:    * Clients of the service can use this attribute to quickly determine whether
michael@0:    * initialization is complete, and decide to trigger some immediate treatment,
michael@0:    * to launch asynchronous initialization or to bailout.
michael@0:    *
michael@0:    * Note that this attribute does not indicate that initialization has succeeded.
michael@0:    *
michael@0:    * @return |true| if the search service is now initialized, |false| if
michael@0:    * initialization has not been triggered yet.
michael@0:    */
michael@0:   readonly attribute bool isInitialized;
michael@0: 
michael@0:   /**
michael@0:    * Adds a new search engine from the file at the supplied URI, optionally
michael@0:    * asking the user for confirmation first.  If a confirmation dialog is
michael@0:    * shown, it will offer the option to begin using the newly added engine
michael@0:    * right away.
michael@0:    *
michael@0:    * @param engineURL
michael@0:    *        The URL to the search engine's description file.
michael@0:    *
michael@0:    * @param dataType
michael@0:    *        An integer representing the plugin file format. Must be one
michael@0:    *        of the supported search engine data types defined above.
michael@0:    *
michael@0:    * @param iconURL
michael@0:    *        A URL string to an icon file to be used as the search engine's
michael@0:    *        icon. This value may be overridden by an icon specified in the
michael@0:    *        engine description file.
michael@0:    *
michael@0:    * @param confirm
michael@0:    *        A boolean value indicating whether the user should be asked for
michael@0:    *        confirmation before this engine is added to the list.  If this
michael@0:    *        value is false, the engine will be added to the list upon successful
michael@0:    *        load, but it will not be selected as the current engine.
michael@0:    *
michael@0:    * @param callback
michael@0:    *        A nsISearchInstallCallback that will be notified when the
michael@0:    *        addition is complete, or if the addition fails. It will not be
michael@0:    *        called if addEngine throws an exception.
michael@0:    *
michael@0:    * @throws NS_ERROR_FAILURE if the type is invalid, or if the description
michael@0:    *         file cannot be successfully loaded.
michael@0:    */
michael@0:   void addEngine(in AString engineURL, in long dataType, in AString iconURL,
michael@0:                  in boolean confirm, [optional] in nsISearchInstallCallback callback);
michael@0: 
michael@0:   /**
michael@0:    * Adds a new search engine, without asking the user for confirmation and
michael@0:    * without starting to use it right away.
michael@0:    *
michael@0:    * @param name
michael@0:    *        The search engine's name. Must be unique. Must not be null.
michael@0:    *
michael@0:    * @param iconURL
michael@0:    *        Optional: A URL string pointing to the icon to be used to represent
michael@0:    *        the engine.
michael@0:    *
michael@0:    * @param alias
michael@0:    *        Optional: A unique shortcut that can be used to retrieve the
michael@0:    *        search engine.
michael@0:    *
michael@0:    * @param description
michael@0:    *        Optional: a description of the search engine.
michael@0:    *
michael@0:    * @param method
michael@0:    *        The HTTP request method used when submitting a search query.
michael@0:    *        Must be a case insensitive value of either "get" or "post".
michael@0:    *
michael@0:    * @param url
michael@0:    *        The URL to which search queries should be sent.
michael@0:    *        Must not be null.
michael@0:    */
michael@0:   void addEngineWithDetails(in AString name,
michael@0:                             in AString iconURL,
michael@0:                             in AString alias,
michael@0:                             in AString description,
michael@0:                             in AString method,
michael@0:                             in AString url);
michael@0: 
michael@0:   /**
michael@0:    * Un-hides all engines installed in the directory corresponding to
michael@0:    * the directory service's NS_APP_SEARCH_DIR key. (i.e. the set of
michael@0:    * engines returned by getDefaultEngines)
michael@0:    */
michael@0:   void restoreDefaultEngines();
michael@0: 
michael@0:   /**
michael@0:    * Returns an engine with the specified alias.
michael@0:    *
michael@0:    * @param   alias
michael@0:    *          The search engine's alias.
michael@0:    * @returns The corresponding nsISearchEngine object, or null if it doesn't
michael@0:    *          exist.
michael@0:    */
michael@0:   nsISearchEngine getEngineByAlias(in AString alias);
michael@0: 
michael@0:   /**
michael@0:    * Returns an engine with the specified name.
michael@0:    *
michael@0:    * @param   aEngineName
michael@0:    *          The name of the engine.
michael@0:    * @returns The corresponding nsISearchEngine object, or null if it doesn't
michael@0:    *          exist.
michael@0:    */
michael@0:   nsISearchEngine getEngineByName(in AString aEngineName);
michael@0: 
michael@0:   /**
michael@0:    * Returns an array of all installed search engines.
michael@0:    *
michael@0:    * @returns an array of nsISearchEngine objects.
michael@0:    */
michael@0:   void getEngines(
michael@0:             [optional] out unsigned long engineCount,
michael@0:             [retval, array, size_is(engineCount)] out nsISearchEngine engines);
michael@0: 
michael@0:   /**
michael@0:    * Returns an array of all installed search engines whose hidden attribute is
michael@0:    * false.
michael@0:    *
michael@0:    * @returns an array of nsISearchEngine objects.
michael@0:    */
michael@0:   void getVisibleEngines(
michael@0:             [optional] out unsigned long engineCount,
michael@0:             [retval, array, size_is(engineCount)] out nsISearchEngine engines);
michael@0: 
michael@0:   /**
michael@0:    * Returns an array of all default search engines. This includes all loaded
michael@0:    * engines that aren't in the user's profile directory
michael@0:    * (NS_APP_USER_SEARCH_DIR).
michael@0:    *
michael@0:    * @returns an array of nsISearchEngine objects.
michael@0:    */
michael@0:   void getDefaultEngines(
michael@0:             [optional] out unsigned long engineCount,
michael@0:             [retval, array, size_is(engineCount)] out nsISearchEngine engines);
michael@0: 
michael@0:   /**
michael@0:    * Moves a visible search engine.
michael@0:    *
michael@0:    * @param  engine
michael@0:    *         The engine to move.
michael@0:    * @param  newIndex
michael@0:    *         The engine's new index in the set of visible engines.
michael@0:    *
michael@0:    * @throws NS_ERROR_FAILURE if newIndex is out of bounds, or if engine is
michael@0:    *         hidden.
michael@0:    */
michael@0:   void moveEngine(in nsISearchEngine engine, in long newIndex);
michael@0: 
michael@0:   /**
michael@0:    * Removes the search engine. If the search engine is installed in a global
michael@0:    * location, this will just hide the engine. If the engine is in the user's
michael@0:    * profile directory, it will be removed from disk.
michael@0:    *
michael@0:    * @param  engine
michael@0:    *         The engine to remove.
michael@0:    */
michael@0:   void removeEngine(in nsISearchEngine engine);
michael@0: 
michael@0:   /**
michael@0:    * The default search engine. Returns the first visible engine if the default
michael@0:    * engine is hidden. May be null if there are no visible search engines.
michael@0:    */
michael@0:   attribute nsISearchEngine defaultEngine;
michael@0: 
michael@0:   /**
michael@0:    * The currently active search engine. May be null if there are no visible
michael@0:    * search engines.
michael@0:    */
michael@0:   attribute nsISearchEngine currentEngine;
michael@0: };
michael@0: 
michael@0: %{ C++
michael@0: /**
michael@0:  * The observer topic to listen to for actions performed on installed
michael@0:  * search engines.
michael@0:  */
michael@0: #define SEARCH_ENGINE_TOPIC "browser-search-engine-modified"
michael@0: 
michael@0: /**
michael@0:  * Sent when an engine is removed from the data store.
michael@0:  */
michael@0: #define SEARCH_ENGINE_REMOVED      "engine-removed"
michael@0: 
michael@0: /**
michael@0:  * Sent when an engine is changed. This includes when the engine's "hidden"
michael@0:  * property is changed.
michael@0:  */
michael@0: #define SEARCH_ENGINE_CHANGED      "engine-changed"
michael@0: 
michael@0: /**
michael@0:  * Sent when an engine is added to the list of available engines.
michael@0:  */
michael@0: #define SEARCH_ENGINE_ADDED        "engine-added"
michael@0: 
michael@0: /**
michael@0:  * Sent when a search engine being installed from a remote plugin description
michael@0:  * file is completely loaded. This is used internally by the search service as
michael@0:  * an indication of when the engine can be added to the internal store, and
michael@0:  * therefore should not be used to detect engine availability. It is always
michael@0:  * followed by an "added" notification.
michael@0:  */
michael@0: #define SEARCH_ENGINE_LOADED       "engine-loaded"
michael@0: 
michael@0: /**
michael@0:  * Sent when the "current" engine is changed.
michael@0:  */
michael@0: #define SEARCH_ENGINE_CURRENT      "engine-current";
michael@0: 
michael@0: /**
michael@0:  * Sent when the "default" engine is changed.
michael@0:  */
michael@0: #define SEARCH_ENGINE_DEFAULT      "engine-default";
michael@0: 
michael@0: 
michael@0: 
michael@0: %}