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.
  * @param   responseType
  *          The MIME type that we'd like to receive in response
  *          to this submission.  If null, will default to "text/html".
  * @returns A nsISearchSubmission object that contains information about what
  *          to send to the search engine.
  */
 nsISearchSubmission getSubmission(in AString data, in AString responseType);

 /**
  * Adds a parameter to the search engine's submission data. This should only
  * be called on engine's 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.
  *
  * @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);

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

 /**
  * A URL string pointing to the engine's search form.
  */
 readonly attribute AString searchForm;

};

nsIBrowserSearchService

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. Must not be null.
  * @param iconURI
  *        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.
  */
 void addEngineWithDetails(in AString name,
                           in AString iconURL,
                           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;  

};