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

 /**
  * 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 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 type of engine to add. Must be
  *              one of the supported search engine types defined above.
  *
  *  @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);

 /**
  * Adds a Sherlock engine.
  *  @param engineURL the URL to the Sherlock ".src" file to add.
  *  @param iconURL the URL to an icon to be used as the engine icon.
  *
  */
 void addSherlockEngine(in AString engineURL, 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);

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

};