toolkit/components/search/nsIBrowserSearchService.idl

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   4  * The contents of this file are subject to the Mozilla Public License Version
   5  * 1.1 (the "License"); you may not use this file except in compliance with
   6  * the License. You may obtain a copy of the License at
   7  * http://www.mozilla.org/MPL/
   8  *
   9  * Software distributed under the License is distributed on an "AS IS" basis,
  10  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11  * for the specific language governing rights and limitations under the
  12  * License.
  13  *
  14  * The Original Code is the Browser Search Service.
  15  *
  16  * The Initial Developer of the Original Code is
  17  * Google Inc.
  18  * Portions created by the Initial Developer are Copyright (C) 2005-2006
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *   Ben Goodger <beng@google.com> (Original author)
  23  *   Gavin Sharp <gavin@gavinsharp.com>
  24  *   Joe Hughes  <joe@retrovirus.com>
  25  *   Pamela Greene <pamg.bugs@gmail.com>
  26  *
  27  * Alternatively, the contents of this file may be used under the terms of
  28  * either the GNU General Public License Version 2 or later (the "GPL"), or
  29  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30  * in which case the provisions of the GPL or the LGPL are applicable instead
  31  * of those above. If you wish to allow use of your version of this file only
  32  * under the terms of either the GPL or the LGPL, and not to allow others to
  33  * use your version of this file under the terms of the MPL, indicate your
  34  * decision by deleting the provisions above and replace them with the notice
  35  * and other provisions required by the GPL or the LGPL. If you do not delete
  36  * the provisions above, a recipient may use your version of this file under
  37  * the terms of any one of the MPL, the GPL or the LGPL.
  38  *
  39  * ***** END LICENSE BLOCK ***** */
  40
  41 #include "nsISupports.idl"
  42
  43 interface nsIURI;
  44 interface nsIInputStream;
  45
  46 [scriptable, uuid(58e4f602-a7c8-4cd1-9dca-716705e826ef)]
  47 interface nsISearchSubmission : nsISupports
  48 {
  49   /**
  50    * The POST data associated with a search submission, wrapped in a MIME
  51    * input stream. May be null.
  52    */
  53   readonly attribute nsIInputStream postData;
  54
  55   /**
  56    * The URI to submit a search to.
  57    */
  58   readonly attribute nsIURI uri;
  59 };
  60
  61 [scriptable, uuid(803e510b-4b27-4ba2-a16d-bb5fa953c166)]
  62 interface nsISearchEngine : nsISupports
  63 {
  64   /**
  65    * Gets a nsISearchSubmission object that contains information about what to
  66    * send to the search engine, including the URI and postData, if applicable.
  67    *
  68    * @param  data
  69    *         Data to add to the submission object.
  70    *         i.e. the search terms.
  71    *
  72    * @param  responseType
  73    *         The MIME type that we'd like to receive in response
  74    *         to this submission.  If null, will default to "text/html".
  75    *
  76    * @returns A nsISearchSubmission object that contains information about what
  77    *          to send to the search engine.  If no submission can be
  78    *          obtained for the given responseType, returns null.
  79    */
  80   nsISearchSubmission getSubmission(in AString data, in AString responseType);
  81
  82   /**
  83    * Adds a parameter to the search engine's submission data. This should only
  84    * be called on engines created via addEngineWithDetails.
  85    *
  86    * @param name
  87    *        The parameter's name. Must not be null.
  88    *
  89    * @param value
  90    *        The value to pass. If value is "{searchTerms}", it will be
  91    *        substituted with the user-entered data when retrieving the
  92    *        submission. Must not be null.
  93    *
  94    * @param responseType
  95    *        Since an engine can have several different request URLs,
  96    *        differentiated by response types, this parameter selects
  97    *        a request to add parameters to.  If null, will default
  98    *        to "text/html"
  99    *
 100    * @throws NS_ERROR_FAILURE if the search engine is read-only.
 101    * @throws NS_ERROR_INVALID_ARG if name or value are null.
 102    */
 103   void addParam(in AString name, in AString value, in AString responseType);
 104
 105   /**
 106    * Determines whether the engine can return responses in the given
 107    * MIME type.  Returns true if the engine spec has a URL with the
 108    * given responseType, false otherwise.
 109    *
 110    * @param responseType
 111    *        The MIME type to check for
 112    */
 113   boolean supportsResponseType(in AString responseType);
 114
 115   /**
 116    * Supported search engine types.
 117    */
 118   const unsigned long TYPE_MOZSEARCH     = 1;
 119   const unsigned long TYPE_SHERLOCK      = 2;
 120   const unsigned long TYPE_OPENSEARCH    = 3;
 121
 122   /**
 123    * Supported search engine data types.
 124    */
 125   const unsigned long DATA_XML     = 1;
 126   const unsigned long DATA_TEXT    = 2;
 127
 128   /**
 129    * The shortcut alias of the engine. This is a unique identifier.
 130    */
 131   attribute AString alias;
 132
 133   /**
 134    * A text description describing the engine.
 135    */
 136   readonly attribute AString description;
 137
 138   /**
 139    * Whether the engine should be hidden from the user.
 140    */
 141   attribute boolean hidden;
 142
 143   /**
 144    * A nsIURI corresponding to the engine's icon, stored locally. May be null.
 145    */
 146   readonly attribute nsIURI iconURI;
 147
 148   /**
 149    * The display name of the search engine. This is a unique identifier.
 150    */
 151   readonly attribute AString name;
 152
 153   /**
 154    * A URL string pointing to the engine's search form.
 155    */
 156   readonly attribute AString searchForm;
 157
 158   /**
 159    * The search engine type.
 160    */
 161   readonly attribute long type;
 162
 163 };
 164
 165 [scriptable, uuid(8307b8f2-08ea-45b8-96bf-b1dc7688fe3b)]
 166 interface nsIBrowserSearchService : nsISupports
 167 {
 168   /**
 169    * Adds a new search engine from the file at the supplied URI, optionally
 170    * asking the user for confirmation first.  If a confirmation dialog is
 171    * shown, it will offer the option to begin using the newly added engine
 172    * right away; if no confirmation dialog is shown, the new engine will be
 173    * used right away automatically.
 174    *
 175    * @param engineURL
 176    *        The URL to the search engine's description file.
 177    *
 178    * @param dataType
 179    *        An integer representing the plugin file format. Must be one
 180    *        of the supported search engine data types defined above.
 181    *
 182    * @param iconURL
 183    *        A URL string to an icon file to be used as the search engine's
 184    *        icon. This value may be overridden by an icon specified in the
 185    *        engine description file.
 186    *
 187    * @param confirm
 188    *        A boolean value indicating whether the user should be asked for
 189    *        confirmation before this engine is added to the list.  If this
 190    *        value is false, the engine will be added to the list upon successful
 191    *        load, but it will not be selected as the current engine.
 192    *
 193    * @throws NS_ERROR_FAILURE if the type is invalid, or if the description
 194    *         file cannot be successfully loaded.
 195    */
 196   void addEngine(in AString engineURL, in long dataType, in AString iconURL,
 197                  in boolean confirm);
 198
 199   /**
 200    * Adds a new search engine, without asking the user for confirmation and
 201    * without starting to use it right away.
 202    *
 203    * @param name
 204    *        The search engine's name. Must be unique. Must not be null.
 205    *
 206    * @param iconURL
 207    *        Optional: A URL string pointing to the icon to be used to represent
 208    *        the engine.
 209    *
 210    * @param alias
 211    *        Optional: A unique shortcut that can be used to retrieve the
 212    *        search engine.
 213    *
 214    * @param description
 215    *        Optional: a description of the search engine.
 216    *
 217    * @param method
 218    *        The HTTP request method used when submitting a search query.
 219    *        Must be a case insensitive value of either "get" or "post".
 220    *
 221    * @param url
 222    *        The URL to which search queries should be sent.
 223    *        Must not be null.
 224    */
 225   void addEngineWithDetails(in AString name,
 226                             in AString iconURL,
 227                             in AString alias,
 228                             in AString description,
 229                             in AString method,
 230                             in AString url);
 231
 232   /**
 233    * Un-hides all engines installed in the directory corresponding to
 234    * the directory service's NS_APP_SEARCH_DIR key. (i.e. the set of
 235    * engines returned by getDefaultEngines)
 236    */
 237   void restoreDefaultEngines();
 238
 239   /**
 240    * Returns an engine with the specified alias.
 241    *
 242    * @param   alias
 243    *          The search engine's alias.
 244    * @returns The corresponding nsISearchEngine object, or null if it doesn't
 245    *          exist.
 246    */
 247   nsISearchEngine getEngineByAlias(in AString alias);
 248
 249   /**
 250    * Returns an engine with the specified name.
 251    *
 252    * @param   aEngineName
 253    *          The name of the engine.
 254    * @returns The corresponding nsISearchEngine object, or null if it doesn't
 255    *          exist.
 256    */
 257   nsISearchEngine getEngineByName(in AString aEngineName);
 258
 259   /**
 260    * Returns an array of all installed search engines.
 261    *
 262    * @returns an array of nsISearchEngine objects.
 263    */
 264   void getEngines(
 265             out unsigned long engineCount,
 266             [retval, array, size_is(engineCount)] out nsISearchEngine engines);
 267
 268   /**
 269    * Returns an array of all installed search engines whose hidden attribute is
 270    * false.
 271    *
 272    * @returns an array of nsISearchEngine objects.
 273    */
 274   void getVisibleEngines(
 275             out unsigned long engineCount,
 276             [retval, array, size_is(engineCount)] out nsISearchEngine engines);
 277
 278   /**
 279    * Returns an array of all default search engines. This includes all loaded
 280    * engines that aren't in the user's profile directory
 281    * (NS_APP_USER_SEARCH_DIR).
 282    *
 283    * @returns an array of nsISearchEngine objects.
 284    */
 285   void getDefaultEngines(
 286             out unsigned long engineCount,
 287             [retval, array, size_is(engineCount)] out nsISearchEngine engines);
 288
 289   /**
 290    * Moves a visible search engine.
 291    *
 292    * @param  engine
 293    *         The engine to move.
 294    * @param  newIndex
 295    *         The engine's new index in the set of visible engines.
 296    *
 297    * @throws NS_ERROR_FAILURE if newIndex is out of bounds, or if engine is
 298    *         hidden.
 299    */
 300   void moveEngine(in nsISearchEngine engine, in long newIndex);
 301
 302   /**
 303    * Removes the search engine. If the search engine is installed in a global
 304    * location, this will just hide the engine. If the engine is in the user's
 305    * profile directory, it will be removed from disk.
 306    *
 307    * @param  engine
 308    *         The engine to remove.
 309    */
 310   void removeEngine(in nsISearchEngine engine);
 311
 312   /**
 313    * The default search engine. May be null if there are no visible
 314    * search engines installed.
 315    */
 316   readonly attribute nsISearchEngine defaultEngine;
 317
 318   /**
 319    * The currently active search engine. May be null if there are no visible
 320    * search engines installed.
 321    */
 322   attribute nsISearchEngine currentEngine;
 323
 324 };
 325
 326 %{ C++
 327 /**
 328  * The observer topic to listen to for actions performed on installed
 329  * search engines.
 330  */
 331 #define SEARCH_ENGINE_TOPIC "browser-search-engine-modified"
 332
 333 /**
 334  * Sent when an engine is removed from the data store.
 335  */
 336 #define SEARCH_ENGINE_REMOVED      "engine-removed"
 337
 338 /**
 339  * Sent when an engine is changed. This includes when the engine's "hidden"
 340  * property is changed.
 341  */
 342 #define SEARCH_ENGINE_CHANGED      "engine-changed"
 343
 344 /**
 345  * Sent when an engine is added to the list of available engines.
 346  */
 347 #define SEARCH_ENGINE_ADDED        "engine-added"
 348
 349 /**
 350  * Sent when a search engine being installed from a remote plugin description
 351  * file is completely loaded. This is used internally by the search service as
 352  * an indication of when the engine can be added to the internal store, and
 353  * therefore should not be used to detect engine availability. It is always
 354  * followed by an "added" notification.
 355  */
 356 #define SEARCH_ENGINE_LOADED       "engine-loaded"
 357
 358 /**
 359  * Sent when the "current" engine is changed.
 360  */
 361 #define SEARCH_ENGINE_CURRENT      "engine-current";
 362
 363 %}