View source for 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;  

};