Search Service:API

This is the proposed API for the the new Firefox search service. 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   aData
  *          User entered input to substitute into the submission data. 
  *          i.e. the search terms.
  * @returns A nsISearchSubmission object that contains information about what
  *          to send to the search engine.
  */
 nsISearchSubmission getSubmission(in AString aData);

 /**
  * 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
  */
 void addParam(in AString name, in AString value);

 /**
  * Supported search engine types.
  */
 const unsigned long TYPE_OPENSEARCH    = 1;
 const unsigned long TYPE_SHERLOCK      = 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.
  */
 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 nsIURI 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.
  */
 void addEngine(in AString engineURI);

 /**
  * This is the old nsInternetSearchService.cpp/nsISidebar API... it needs
  * to be supported, though the last two params will probably be ignored.
  */
 void addSearchEngine(in AString engineURL,
                      in AString iconURL,
                      in AString suggestedTitle,
                      in AString suggestedCategory);

 /**
  * Adds a new search engine.
  * @param name
  *        The search engine's name. Must be unique.
  * @param iconURI
  *        A nsIURI pointing to the icon to be used to represent the engine.
  *        Only supports HTTP/HTTPS/File protocols, all others will be
  *        rejected.
  *        HTTP/HTTPS icons will be downloaded to the user's search plugin
  *        directory.
  * @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 template
  *        The URL to which search queries should be sent. This value will
  *        undergo parameter substition according to the OpenSearch 1.1
  *        specification.
  *        XXX only some parameters are supported
  *        Example value: "http://browser.search.example.com/?query={searchTerms}
  *        See http://opensearch.a9.com/spec/1.1/querysyntax/#parameter-syntax.
  */
 void addEngineWithDetails(in AString name,
                           in nsIURI iconURI,
                           in AString alias,
                           in AString description,
                           in AString method,
                           in AString template);

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

 /**
  * Removes the search engine (from disk, too).
  * XXX
  * @param   engine
  *          The engine to remove.
  */
 void removeEngine(in nsISearchEngine engine);

 /**
  * Update all the stored search engines.
  * XXX
  */
 void updateEngines();

};