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.

interface nsISearchSubmission : nsISupports {

 /**
  * The POST data associated with a search submission, wrapped in a MIME
  * input stream.
  */
 readonly attribute nsIInputStream postData;
 /**
  * The URI to submit a search to.
  */
 readonly attribute nsIURI uri;

};

interface nsISearchEngine : nsISupports {

 /**
  * Gets a Submission object that contains information about what to send to
  * the search engine including URI and postData. 
  * @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);

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

 /**
  * The shortcut alias of the engine. The alias 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;

};

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. 
  */
 void addEngineWithDetails(
                    in AString name,
                    in nsIURI iconURI,
                    in AString alias,
                    in AString description,
                    in ACString method,
                    in AString template,
                    in unsigned long paramNameCount,
                    [array, size_is(paramNameCount)] in wstring paramNames,
                    in unsigned long paramValueCount,
                    [array, size_is(paramValueCount)] in wstring paramValues);

 /**
  * Returns an engine with the specified alias.
  * @param   aAlias
  *          The search engine's alias.
  * @returns A nsISearchEngine object
  */
 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 all installed search engines.
  */
 void getEngines(out unsigned long engineCount, 
                 [retval, array, size_is(engineCount)] out nsISearchEngine engines);

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

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

};