summaryrefslogtreecommitdiffstats
path: root/toolkit/components/search/nsISearchService.idl
blob: 769ba4eca7285fbdc7c74d5b64d00f7b95be9edb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIURI;
interface nsIInputStream;

[scriptable, uuid(5799251f-5b55-4df7-a9e7-0c27812c469a)]
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;
};

[scriptable, uuid(620bd920-0491-48c8-99a8-d6047e64802d)]
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 searchTerms
   *   The search term(s) for the submission.
   *
   * @param responseType [optional]
   *   The MIME type that we'd like to receive in response
   *   to this submission.  If null, will default to "text/html".
   *
   * @param purpose [optional]
   *   A string that indicates the context of the search request. This may then
   *   be used to provide different submission data depending on the context.
   *
   * @returns nsISearchSubmission
   *   The submission data. If no appropriate submission can be determined for
   *   the request type, this may be null.
   */
  nsISearchSubmission getSubmission(in AString searchTerms,
                                    [optional] in AString responseType,
                                    [optional] in AString purpose);
  /**
   * Returns the search term of a possible search result URI if and only if:
   * - The URI has the same scheme, host, and path as the engine.
   * - All query parameters of the URI have a matching name and value in the engine.
   * - An exception to the equality check is the engine's termsParameterName
   *   value, which contains a placeholder, i.e. {searchTerms}.
   * - If an engine has query parameters with "null" values, they will be ignored.
   *
   * @param  uri
   *         A URI that may or may not be from a search result matching the engine.
   *
   * @returns A string representing the termsParameterName value of the URI,
   *          or an empty string if the URI isn't matched to the engine.
   */
  AString searchTermFromResult(in nsIURI uri);

  /**
   * Returns the name of the parameter used for the search terms for a submission
   * URL of type `SearchUtils.URL_TYPE.SEARCH`.
   *
   * @returns A string which is the name of the parameter, or empty string
   *          if no parameter cannot be found or is not supported (e.g. POST).
   */
  readonly attribute AString searchUrlQueryParamName;

  /**
   * Returns the public suffix for the submission URL of type
   * `SearchUtils.URL_TYPE.SEARCH`.
   *
   * @returns A string which is a known public suffix, or empty string
   *          if one cannot be found.
   */
  readonly attribute AString searchUrlPublicSuffix;

  /**
   * Determines whether the engine can return responses in the given
   * MIME type.  Returns true if the engine spec has a URL with the
   * given responseType, false otherwise.
   *
   * @param responseType
   *        The MIME type to check for
   */
  boolean supportsResponseType(in AString responseType);

  /**
   * Returns a string with the URL to an engine's icon matching both width and
   * height. Returns undefined if icon with specified dimensions is not found.
   *
   * @param preferredWidth
   *   Width of the requested icon. If not specified, it is assumed that
   *   16x16 is desired.
   */
  jsval getIconURL([optional] in unsigned short preferredWidth);

  /**
   * Opens a speculative connection to the engine's search URI
   * (and suggest URI, if different) to reduce request latency
   *
   * @param  options
   *         An object that must contain the following fields:
   *         {window} the content window for the window performing the search
   *         {originAttributes} the originAttributes for performing the search
   *
   * @throws NS_ERROR_INVALID_ARG if options is omitted or lacks required
   *         elemeents
   */
  void speculativeConnect(in jsval options);

  /**
   * A user defined alias for the engine.
   * When not an empty string, this should be a unique identifier.
   */
  attribute AString alias;

  /**
   * An array of aliases including the user defined alias and
   * ones specified by the webextensions keywords field.
   */
  readonly attribute Array<AString> aliases;

  /**
   * A text description describing the engine.
   */
  readonly attribute AString description;

  /**
   * Whether the engine should be hidden from the user.
   */
  attribute boolean hidden;

  /**
   * Whether the associated one off button should be hidden from the user.
   */
  attribute boolean hideOneOffButton;

  /**
   * The display name of the search engine. This is a unique identifier.
   */
  readonly attribute AString name;

  /**
   * The display of the search engine id. This is a unique identifier.
   */
  readonly attribute AString id;

  /**
   * The searchForm URL points to the engine's organic search page. This should
   * not contain neither search term parameters nor partner codes, but may
   * contain parameters which set the engine in the correct way.
   *
   * This URL is typically the prePath and filePath of the search submission URI,
   * but may vary for different engines. For example, some engines may use a
   * different domain, e.g. https://sub.example.com for the search URI but
   * https://example.org/ for the organic search page.
   */
  readonly attribute AString searchForm;

  /**
   * The identifier to use for this engine when submitting to telemetry.
   */
  readonly attribute AString telemetryId;

  /**
   * An optional unique identifier for this search engine within the context of
   * the distribution, as provided by the distributing entity.
   */
  readonly attribute AString identifier;

  /**
   * Whether or not this engine is provided by the application, e.g. it is
   * in the list of configured search engines.
   */
  readonly attribute boolean isAppProvided;

  /**
   * Whether or not this engine is an in-memory only search engine.
   * These engines are typically application provided or policy engines,
   * where they are loaded every time on SearchService initialization
   * using the policy JSON or the extension manifest. Minimal details of the
   * in-memory engines are saved to disk, but they are never loaded
   * from the user's saved settings file.
   */
  readonly attribute boolean inMemory;

  /**
   * Whether or not this engine is a "general" search engine, e.g. is it for
   * generally searching the web, or does it have a specific purpose like
   * shopping.
   */
  readonly attribute boolean isGeneralPurposeEngine;

  /**
   * The domain from which search results are returned for this engine.
   *
   * @return the domain of the the search URL.
   */
  readonly attribute AString searchUrlDomain;

  /**
   * The URL to report the search to.
   *
   * @return the reporting URL.
   */
  readonly attribute AString clickUrl;
};

[scriptable, uuid(0dc93e51-a7bf-4a16-862d-4b3469ff6206)]
interface nsISearchParseSubmissionResult : nsISupports
{
  /**
   * The search engine associated with the URL passed in to
   * nsISearchEngine::parseSubmissionURL, or null if the URL does not represent
   * a search submission.
   */
  readonly attribute nsISearchEngine engine;

  /**
   * String containing the sought terms.  This can be an empty string in case no
   * terms were specified or the URL does not represent a search submission.
   */
  readonly attribute AString terms;

  /**
   * The name of the query parameter used by `engine` for queries. E.g. "q".
   */
  readonly attribute AString termsParameterName;
};

[scriptable, uuid(0301834b-2630-440e-8b98-db8dc55f34b9)]
interface nsISearchService : nsISupports
{
  const unsigned long ERROR_DOWNLOAD_FAILURE = 0x1;
  const unsigned long ERROR_DUPLICATE_ENGINE = 0x2;
  const unsigned long ERROR_ENGINE_CORRUPTED = 0x3;

  const unsigned short CHANGE_REASON_UNKNOWN = 0x0;
  const unsigned short CHANGE_REASON_USER = 0x1;
  const unsigned short CHANGE_REASON_USER_PRIVATE_SPLIT = 0x2;
  const unsigned short CHANGE_REASON_USER_SEARCHBAR = 0x3;
  const unsigned short CHANGE_REASON_USER_SEARCHBAR_CONTEXT = 0x4;
  const unsigned short CHANGE_REASON_ADDON_INSTALL = 0x5;
  const unsigned short CHANGE_REASON_ADDON_UNINSTALL = 0x6;
  const unsigned short CHANGE_REASON_CONFIG = 0x7;
  const unsigned short CHANGE_REASON_LOCALE = 0x8;
  const unsigned short CHANGE_REASON_REGION = 0x9;
  const unsigned short CHANGE_REASON_EXPERIMENT = 0xA;
  const unsigned short CHANGE_REASON_ENTERPRISE = 0xB;
  const unsigned short CHANGE_REASON_UITOUR = 0xC;
  const unsigned short CHANGE_REASON_ENGINE_UPDATE = 0xD;

  /**
   * Start asynchronous initialization.
   *
   * The promise is resolved once initialization is complete, which may be
   * immediately, if initialization has already been completed by some previous
   * call to this method.
   * This method should only be called when you need or want to wait for the
   * full initialization of the search service.
   */
  Promise init();

  /**
   * A promise that is resolved when initialization has finished, but does not
   * trigger initialization to begin.
   *
   * @returns {Promise}
   *   Resolved when initalization has successfully finished, and rejected if it
   *   has failed.
   */
  readonly attribute Promise promiseInitialized;

  /**
   * Determine whether initialization has been completed.
   *
   * Clients of the service can use this attribute to quickly determine whether
   * initialization is complete, and decide to trigger some immediate treatment,
   * to launch asynchronous initialization or to bailout.
   *
   * Note that this attribute does not indicate that initialization has succeeded.
   *
   * @return |true| if the search service is now initialized, |false| if
   * initialization has not been triggered yet.
   */
  readonly attribute bool isInitialized;

  /**
   * Determine whether initialization has been completed successfully.
   *
   */
  readonly attribute bool hasSuccessfullyInitialized;


  /**
   * Runs background checks; Designed to be run on idle.
   */
  Promise runBackgroundChecks();

  /**
   * Resets the default engine to its app default engine value.
   */
  Promise resetToAppDefaultEngine();

  /**
   * Adds a new Open Search engine from the file at the supplied URI.
   *
   * @param engineURL
   *        The URL to the search engine's description file.
   *
   * @param iconURL
   *        A URL string to an icon file to be used as the search engine's
   *        icon. This value may be overridden by an icon specified in the
   *        engine description file.
   *
   * @throws NS_ERROR_FAILURE if the description file cannot be successfully
   *         loaded.
   */
  Promise addOpenSearchEngine(in AString engineURL, in AString iconURL);

  /**
   * Adds a new search engine defined by the user.
   *
   * @param name
   *        The name of the engine.
   * @param url
   *        The url of the engine with %s denoting where to
   *        replace the search term.
   * @param alias [optional]
   *        The alias to refer to the engine.
   */
  Promise addUserEngine(in AString name,
                        in AString url,
                        [optional] in AString alias);

  /**
   * Adds search providers to the search service.  If the search
   * service is configured to load multiple locales for the extension,
   * it may load more than one search engine. If called directly
   * ensure the extension has been initialised.
   *
   * @param extension
   *        The extension to load from.
   * @returns Promise that resolves when finished.
   */
  Promise addEnginesFromExtension(in jsval extension);

  /**
   * Un-hides all engines in the set of engines returned by getAppProvidedEngines.
   */
  void restoreDefaultEngines();

  /**
   * 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.
   */
  Promise 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 engine with the specified Id.
   *
   * @param   aEngineId
   *          The Id of the engine.
   * @returns The corresponding nsISearchEngine object, or null if it doesn't
   *          exist.
   */
  nsISearchEngine getEngineById(in AString aEngineId);

  /**
   * Returns an array of all installed search engines.
   * The array is sorted either to the user requirements or the default order.
   *
   * @returns an array of nsISearchEngine objects.
   */
  Promise getEngines();

  /**
   * Returns an array of all installed search engines whose hidden attribute is
   * false.
   * The array is sorted either to the user requirements or the default order.
   *
   * @returns an array of nsISearchEngine objects.
   */
  Promise getVisibleEngines();

  /**
   * Returns an array of all default search engines. This includes all loaded
   * engines that aren't in the user's profile directory.
   * The array is sorted to the default order.
   *
   * @returns an array of nsISearchEngine objects.
   */
  Promise getAppProvidedEngines();

  /**
   * Returns an array of search engines installed by a given extension.
   *
   * @returns an array of nsISearchEngine objects.
   */
  Promise getEnginesByExtensionID(in AString extensionID);

  /**
   * Moves a visible search engine.
   *
   * @param  engine
   *         The engine to move.
   * @param  newIndex
   *         The engine's new index in the set of visible engines.
   *
   * @throws NS_ERROR_FAILURE if newIndex is out of bounds, or if engine is
   *         hidden.
   */
  Promise moveEngine(in nsISearchEngine engine, in long newIndex);

  /**
   * 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.
   */
  Promise removeEngine(in nsISearchEngine engine);

  /**
   * Notify nsSearchService that an extension has been removed. Removes any
   * engines that are associated with that extension.
   *
   * @param  id
   *         The id of the extension.
   */
  Promise removeWebExtensionEngine(in AString id);

  /**
   * The Application Default Engine object that is the default for this region,
   * ignoring changes the user may have subsequently made.
   */
  readonly attribute nsISearchEngine appDefaultEngine;

  /**
   * The Application Default Engine object that is the default for this region when in
   * private browsing mode, ignoring changes the user may have subsequently made.
   */
  readonly attribute nsISearchEngine appPrivateDefaultEngine;

  /**
   * The currently active search engine.
   * Unless the application doesn't ship any search plugin, this should never
   * be null. If the currently active engine is removed, this attribute will
   * fallback first to the application default engine if it's not hidden, then to
   * the first visible engine, and as a last resort it will unhide the app
   * default engine.
   */
  attribute nsISearchEngine defaultEngine;

  Promise getDefault();
  Promise setDefault(in nsISearchEngine engine, in unsigned short changeSource);

  /**
   * The currently active search engine for private browsing mode.
   * @see defaultEngine.
   */
  attribute nsISearchEngine defaultPrivateEngine;

  Promise getDefaultPrivate();
  Promise setDefaultPrivate(
    in nsISearchEngine engine,
    in unsigned short changeSource);

  /**
   * Whether to display the "Search in Private Window" result in the urlbar.
   */
  readonly attribute boolean separatePrivateDefaultUrlbarResultEnabled;

  /**
   * Allows the add-on manager to discover if a WebExtension based search engine
   * may change the default to an application provided search engine.
   * If that WebExtension is on the allow list, then it will override the
   * built-in engine's urls and parameters.
   *
   *  @param extension
   *        The extension to load from.
   *  @returns An object with two booleans:
   *        - canChangeToAppProvided: indicates if the WebExtension engine may
   *            set the named engine as default e.g. it is application provided.
   *        - canInstallEngine: indicates if the WebExtension engine may be
   *            installed, e.g. it is not an app-provided engine.
   */
  Promise maybeSetAndOverrideDefault(in jsval extension);

  /**
   * Gets a representation of the default engine in an anonymized JSON
   * string suitable for recording in the Telemetry environment.
   *
   * @return {object} result
   *   contains anonymized info about the default engine(s).
   * @return {string} result.defaultSearchEngine
   *   contains the telemetry id of the default engine.
   * @return {object} result.defaultSearchEngineData
   *   contains information about the default engine:
   *     name, loadPath, original submissionURL
   * @return {string} [result.defaultPrivateSearchEngine]
   *   only returned if the preference for having a separate engine in private
   *   mode is turned on.
   *   contains the telemetry id of the default engine for private browsing mode.
   * @return {object} [result.defaultPrivateSearchEngineData]
   *   only returned if the preference for having a separate engine in private
   *   mode is turned on.
   *   contains information about the default engine for private browsing mode:
   *     name, loadPath, original submissionURL
   */
  jsval getDefaultEngineInfo();

  /**
   * Determines if the provided URL represents results from a search engine, and
   * provides details about the match.
   *
   * The lookup mechanism checks whether the domain name and path of the
   * provided HTTP or HTTPS URL matches one of the known values for the visible
   * search engines.  The match does not depend on which of the schemes is used.
   * The expected URI parameter for the search terms must exist in the query
   * string, but other parameters are ignored.
   *
   * @param url
   *        String containing the URL to parse, for example
   *        "https://www.google.com/search?q=terms".
   */
  nsISearchParseSubmissionResult parseSubmissionURL(in AString url);
};