MozillaWiki

Search Service:API: Difference between revisions

Page Discussion

Search Service:API (view source)

Revision as of 17:03, 18 June 2006

1,158 bytes added ,  18 June 2006
→‎nsISearchEngine
No edit summary
 
(11 intermediate revisions by one other user not shown)
Line 1: Line 1:
This is the proposed API for the the new Firefox search service. Please comment on the discussion page or in the bug itself.
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=
=nsISearchSubmission=
Line 6: Line 6:
   /**
   /**
   * The POST data associated with a search submission, wrapped in a MIME
   * The POST data associated with a search submission, wrapped in a MIME
   * input stream.
   * input stream. May be null.
   */
   */
   readonly attribute nsIInputStream postData;
   readonly attribute nsIInputStream postData;
Line 20: Line 20:
{
{
   /**
   /**
   * Gets a Submission object that contains information about what to send to
   * Gets a nsISearchSubmission object that contains information about what to
   * the search engine, including the URI and postData, if applicable.  
   * send to the search engine, including the URI and postData, if applicable.  
   * @param  aData
   * @param  data
   *          User entered input to substitute into the submission data.  
   *          Data to add to the submission object.
   *          i.e. the search terms.
   *          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
   * @returns A nsISearchSubmission object that contains information about what
   *          to send to the search engine.
   *          to send to the search engine.
   */
   */
   nsISearchSubmission getSubmission(in AString aData);
   nsISearchSubmission getSubmission(in AString data, in AString responseType);


   /**
   /**
   * Adds a parameter to the search engine's submission data.
   * Adds a parameter to the search engine's submission data. This should only
  * be called on engine's created via addEngineWithDetails.
   * @param name
   * @param name
   *        The parameter's name.
   *        The parameter's name. Must not be null.
   * @param value
   * @param value
   *        The value to pass. This can be one of the  
   *        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);
   void addParam(in AString name, in AString value);
Line 42: Line 51:
   * Supported search engine types.
   * Supported search engine types.
   */
   */
   const unsigned long TYPE_OPENSEARCH    = 1;
   const unsigned long TYPE_MOZSEARCH    = 1;
   const unsigned long TYPE_SHERLOCK      = 2;
   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;


   /**
   /**
Line 58: Line 74:
   * A nsIURI corresponding to the engine's icon, stored locally. May be null.
   * A nsIURI corresponding to the engine's icon, stored locally. May be null.
   */
   */
   attribute nsIURI iconURI;
   readonly attribute nsIURI iconURI;


   /**
   /**
Line 64: Line 80:
   * iconURI.spec, or an empty string if the engine has no iconURI.
   * iconURI.spec, or an empty string if the engine has no iconURI.
   */
   */
   readonly attribute nsIURI iconURL;
   readonly attribute AString iconURL;


   /**
   /**
Line 75: Line 91:
   */
   */
   readonly attribute long type;
   readonly attribute long type;
  /**
  * A URL string pointing to the engine's search form.
  */
  readonly attribute AString searchForm;
};
};


=nsISearchService=
=nsIBrowserSearchService=
interface nsISearchService : nsISupports
interface nsISearchService : nsISupports
{
{
   /**
   /**
   * Adds a new search engine from the file at the supplied URI.
   * 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 engineURI);
   void addEngine(in AString engineURL, in long type, in AString iconURL);
 
  /**
  * 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.
   * Adds a new search engine.
   * @param name
   * @param name
   *        The search engine's name. Must be unique.
   *        The search engine's name. Must be unique. Must not be null.
   * @param iconURI
   * @param iconURI
   *        A nsIURI pointing to the icon to be used to represent the engine.
   *        Optional: A URL string pointing to the icon to be used to represent
  *        Only supports HTTP/HTTPS/File protocols, all others will be
   *        the engine.
  *        rejected.
   *        HTTP/HTTPS icons will be downloaded to the user's search plugin
  *        directory.
   * @param alias
   * @param alias
   *        A unique shortcut that can be used to retrieve the search engine.
   *        Optional: A unique shortcut that can be used to retrieve the
  *        search engine.
   * @param description
   * @param description
   *        A description of the search engine.
   *        Optional: a description of the search engine.
   * @param method
   * @param method
   *        The HTTP request method used when submitting a search query.
   *        The HTTP request method used when submitting a search query.
   *        Must be a case insensitive value of either "get" or "post".
   *        Must be a case insensitive value of either "get" or "post".
   * @param template
   * @param url
   *        The URL to which search queries should be sent. This value will
   *        The URL to which search queries should be sent.
   *        undergo parameter substition according to the OpenSearch 1.1
   *        Must not be null.
  *        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,
   void addEngineWithDetails(in AString name,
                             in nsIURI iconURI,
                             in AString iconURL,
                             in AString alias,
                             in AString alias,
                             in AString description,
                             in AString description,
                             in AString method,
                             in AString method,
                             in AString template);
                             in AString url);


   /**
   /**
Line 148: Line 163:
   * @returns an array of nsISearchEngine objects.
   * @returns an array of nsISearchEngine objects.
   */
   */
   void getEngines(out unsigned long engineCount,  
   void getEngines(
                  [retval, array, size_is(engineCount)] out nsISearchEngine engines);
            out unsigned long engineCount,  
            [retval, array, size_is(engineCount)] out nsISearchEngine engines);


   /**
   /**
   * Removes the search engine (from disk, too).
  * Returns an array of all installed search engines whose hidden attribute is
   * XXX
  * 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
   * @param  engine
   *          The engine to remove.
   *          The engine to remove.
Line 160: Line 188:


   /**
   /**
   * Update all the stored search engines.
   * The default search engine.
  * XXX
   */
   */
   void updateEngines();
   readonly attribute nsISearchEngine defaultEngine;
 
  /**
  * The currently active search engine.
  */
  attribute nsISearchEngine currentEngine; 
 
};
};
-dt-
1

edit

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/16629...28012"