Search Service:API

This is the proposed API for the the new Firefox search service. It is not yet final. Please comment on the discussion page or in the bug itself.

nsISearchSubmission

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;

};

nsISearchEngine

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.
  * @returns A nsISearchSubmission object that contains information about what
  *          to send to the search engine.
  */
 nsISearchSubmission getSubmission(in AString data);

 /**
  * Adds a parameter to the search engine's submission data.
  * @param name
  *        The parameter's name.
  * @param value
  *        The value to pass. If value is "{searchTerms}", it will be
  *        substituted with the user-entered data when retrieving the
  *        submission. XXX
  *
  * @throws NS_ERROR_FAILURE if the search engine is read-only.
  */
 void addParam(in AString name, in AString value);

 /**
  * Supported search engine types.
  */
 const unsigned long TYPE_MOZSEARCH     = 1;
 const unsigned long TYPE_SHERLOCK      = 2;
 const unsigned long TYPE_OPENSEARCH    = 3;

 /**
  * Supported search engine data types.
  */
 const unsigned long DATA_XML     = 1;
 const unsigned long DATA_TEXT    = 2;

 /**
  * The shortcut alias of the engine. This is a unique identifier.
  */
 attribute AString alias;

 /**
  * 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;

 /**
  * A string corresponding to the engine icon's URL. This will return
  * iconURI.spec, or an empty string if the engine has no iconURI.
  */
 readonly attribute AString iconURL;

 /**
  * The display name of the search engine. This is a unique identifier.
  */
 readonly attribute AString name;

 /**
  * The search engine type.
  */
 readonly attribute long type;

};

nsISearchService

interface nsISearchService : nsISupports {

 /**
  * Adds a new search engine from the file at the supplied URI.
  *  @param engineURL the URL to the search engine's description file.
  *  @param type an integer representing the plugin file format. Must be one
  *         of the supported search engine data types defined above.
  *  @param iconURL the URL to an icon file to be used as the search engine's
  *         icon.
  *
  *  @throws NS_ERROR_FAILURE if the type is invalid, or if the description
  *          file cannot be successfully loaded.
  */
 void addEngine(in AString engineURL, in long type, in AString iconURL);

 /**
  * Adds a new search engine.
  * @param name
  *        The search engine's name. Must be unique.
  * @param iconURI
  *        A URI pointing to the icon to be used to represent the engine.
  *        Only supports HTTP/HTTPS protocols, all others will be rejected.
  * @param alias
  *        A unique shortcut that can be used to retrieve the search engine.
  * @param description
  *        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.
  */
 void addEngineWithDetails(in AString name,
                           in nsIURI iconURI,
                           in AString alias,
                           in AString description,
                           in AString method,
                           in AString url);

 /**
  * 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(
           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(
           out unsigned long engineCount, 
           [retval, array, size_is(engineCount)] out nsISearchEngine engines);

 /**
  * 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 default search engine.
  */
 readonly attribute nsISearchEngine defaultEngine;

 /**
  * The currently active search engine.
  */
 attribute nsISearchEngine currentEngine;  

};