MozillaWiki

Search Service:API: Difference between revisions

Page Discussion

Search Service:API (view source)

Revision as of 17:03, 18 June 2006

2,668 bytes added ,  18 June 2006
→‎nsISearchEngine
No edit summary
 
(17 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=
interface nsISearchSubmission : nsISupports
interface nsISearchSubmission : nsISupports
{
{
   /**
   /**
   * 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;
   /**
   /**
   * The URI to submit a search to.
   * The URI to submit a search to.
Line 14: Line 16:
};
};


=nsISearchEngine=
interface nsISearchEngine : nsISupports
interface nsISearchEngine : nsISupports
{
{
   /**
   /**
   * 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 URI and postData.  
   * 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. 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.
   * 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;


   /**
   /**
   * The shortcut alias of the engine. The alias is a unique identifier.
   * The shortcut alias of the engine. This is a unique identifier.
   */
   */
   attribute AString alias;
   attribute AString alias;
Line 46: 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 52: 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 63: Line 91:
   */
   */
   readonly attribute long type;
   readonly attribute long type;
  /**
  * A URL string pointing to the engine's search form.
  */
  readonly attribute AString searchForm;
};
};


=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  
   * @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(
   void addEngineWithDetails(in AString name,
                    in AString name,
                            in AString iconURL,
                    in nsIURI iconURI,
                            in AString alias,
                    in AString alias,
                            in AString description,
                    in AString description,
                            in AString method,
                    in AString method,
                            in AString url);
                    in AString template);


   /**
   /**
Line 97: Line 145:
   * @param  alias
   * @param  alias
   *          The search engine's alias.
   *          The search engine's alias.
   * @returns A nsISearchEngine object
   * @returns The corresponding nsISearchEngine object, or null if it doesn't
  *          exist.
   */
   */
   nsISearchEngine getEngineByAlias(in AString alias);
   nsISearchEngine getEngineByAlias(in AString alias);
Line 112: Line 161:
   /**
   /**
   * Returns an array of all installed search engines.
   * Returns an array of all installed search engines.
   * @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
  * 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 125: Line 188:


   /**
   /**
   * Update all the stored search engines.
   * The default search engine.
   */
   */
   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/16618...28012"