The Tor Browser / file comparison

comparison: netwerk/base/public/nsIBrowserSearchService.idl

netwerk/base/public/nsIBrowserSearchService.idl

branch
TOR_BUG_9701
changeset 15
b8a032363ba2
equal deleted inserted replaced
-1:000000000000 0:65ca325af542
1 /* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
4
5 #include "nsISupports.idl"
6
7 interface nsIURI;
8 interface nsIInputStream;
9
10 [scriptable, uuid(5799251f-5b55-4df7-a9e7-0c27812c469a)]
11 interface nsISearchSubmission : nsISupports
12 {
13 /**
14 * The POST data associated with a search submission, wrapped in a MIME
15 * input stream. May be null.
16 */
17 readonly attribute nsIInputStream postData;
18
19 /**
20 * The URI to submit a search to.
21 */
22 readonly attribute nsIURI uri;
23 };
24
25 [scriptable, uuid(77de6680-57ec-4105-a183-cc7cf7e84b09)]
26 interface nsISearchEngine : nsISupports
27 {
28 /**
29 * Gets a nsISearchSubmission object that contains information about what to
30 * send to the search engine, including the URI and postData, if applicable.
31 *
32 * @param data
33 * Data to add to the submission object.
34 * i.e. the search terms.
35 *
36 * @param responseType [optional]
37 * The MIME type that we'd like to receive in response
38 * to this submission. If null, will default to "text/html".
39 *
40 * @param purpose [optional]
41 * A string meant to indicate the context of the search request. This
42 * allows the search service to provide a different nsISearchSubmission
43 * depending on e.g. where the search is triggered in the UI.
44 *
45 * @returns A nsISearchSubmission object that contains information about what
46 * to send to the search engine. If no submission can be
47 * obtained for the given responseType, returns null.
48 */
49 nsISearchSubmission getSubmission(in AString data,
50 [optional] in AString responseType,
51 [optional] in AString purpose);
52
53 /**
54 * Adds a parameter to the search engine's submission data. This should only
55 * be called on engines created via addEngineWithDetails.
56 *
57 * @param name
58 * The parameter's name. Must not be null.
59 *
60 * @param value
61 * The value to pass. If value is "{searchTerms}", it will be
62 * substituted with the user-entered data when retrieving the
63 * submission. Must not be null.
64 *
65 * @param responseType
66 * Since an engine can have several different request URLs,
67 * differentiated by response types, this parameter selects
68 * a request to add parameters to. If null, will default
69 * to "text/html"
70 *
71 * @throws NS_ERROR_FAILURE if the search engine is read-only.
72 * @throws NS_ERROR_INVALID_ARG if name or value are null.
73 */
74 void addParam(in AString name, in AString value, in AString responseType);
75
76 /**
77 * Determines whether the engine can return responses in the given
78 * MIME type. Returns true if the engine spec has a URL with the
79 * given responseType, false otherwise.
80 *
81 * @param responseType
82 * The MIME type to check for
83 */
84 boolean supportsResponseType(in AString responseType);
85
86 /**
87 * Returns a string with the URL to an engine's icon matching both width and
88 * height. Returns null if icon with specified dimensions is not found.
89 *
90 * @param width
91 * Width of the requested icon.
92 * @param height
93 * Height of the requested icon.
94 */
95 AString getIconURLBySize(in long width, in long height);
96
97 /**
98 * Gets an array of all available icons. Each entry is an object with
99 * width, height and url properties. width and height are numeric and
100 * represent the icon's dimensions. url is a string with the URL for
101 * the icon.
102 */
103 jsval getIcons();
104
105 /**
106 * Supported search engine types.
107 */
108 const unsigned long TYPE_MOZSEARCH = 1;
109 const unsigned long TYPE_SHERLOCK = 2;
110 const unsigned long TYPE_OPENSEARCH = 3;
111
112 /**
113 * Supported search engine data types.
114 */
115 const unsigned long DATA_XML = 1;
116 const unsigned long DATA_TEXT = 2;
117
118 /**
119 * An optional shortcut alias for the engine.
120 * When non-null, this is a unique identifier.
121 */
122 attribute AString alias;
123
124 /**
125 * A text description describing the engine.
126 */
127 readonly attribute AString description;
128
129 /**
130 * Whether the engine should be hidden from the user.
131 */
132 attribute boolean hidden;
133
134 /**
135 * A nsIURI corresponding to the engine's icon, stored locally. May be null.
136 */
137 readonly attribute nsIURI iconURI;
138
139 /**
140 * The display name of the search engine. This is a unique identifier.
141 */
142 readonly attribute AString name;
143
144 /**
145 * A URL string pointing to the engine's search form.
146 */
147 readonly attribute AString searchForm;
148
149 /**
150 * The search engine type.
151 */
152 readonly attribute long type;
153
154 /**
155 * An optional unique identifier for this search engine within the context of
156 * the distribution, as provided by the distributing entity.
157 */
158 readonly attribute AString identifier;
159
160 /**
161 * Gets a string representing the hostname from which search results for a
162 * given responseType are returned, minus the leading "www." (if present).
163 * This can be specified as an url attribute in the engine description file,
164 * but will default to host from the <Url>'s template otherwise.
165 *
166 * @param responseType [optional]
167 * The MIME type to get resultDomain for. Defaults to "text/html".
168 *
169 * @return the resultDomain for the given responseType.
170 */
171 AString getResultDomain([optional] in AString responseType);
172 };
173
174 [scriptable, uuid(9fc39136-f08b-46d3-b232-96f4b7b0e235)]
175 interface nsISearchInstallCallback : nsISupports
176 {
177 const unsigned long ERROR_UNKNOWN_FAILURE = 0x1;
178 const unsigned long ERROR_DUPLICATE_ENGINE = 0x2;
179
180 /**
181 * Called to indicate that the engine addition process succeeded.
182 *
183 * @param engine
184 * The nsISearchEngine object that was added (will not be null).
185 */
186 void onSuccess(in nsISearchEngine engine);
187
188 /**
189 * Called to indicate that the engine addition process failed.
190 *
191 * @param errorCode
192 * One of the ERROR_* values described above indicating the cause of
193 * the failure.
194 */
195 void onError(in unsigned long errorCode);
196 };
197
198 /**
199 * Callback for asynchronous initialization of nsIBrowserSearchService
200 */
201 [scriptable, function, uuid(02256156-16e4-47f1-9979-76ff98ceb590)]
202 interface nsIBrowserSearchInitObserver : nsISupports
203 {
204 /**
205 * Called once initialization of the browser search service is complete.
206 *
207 * @param aStatus The status of that service.
208 */
209 void onInitComplete(in nsresult aStatus);
210 };
211
212 [scriptable, uuid(939d74a4-5b01-463c-80c7-4301f0c0f9ef)]
213 interface nsIBrowserSearchService : nsISupports
214 {
215 /**
216 * Start asynchronous initialization.
217 *
218 * The callback is triggered once initialization is complete, which may be
219 * immediately, if initialization has already been completed by some previous
220 * call to this method. The callback is always invoked asynchronously.
221 *
222 * @param aObserver An optional object observing the end of initialization.
223 */
224 void init([optional] in nsIBrowserSearchInitObserver aObserver);
225
226 /**
227 * Determine whether initialization has been completed.
228 *
229 * Clients of the service can use this attribute to quickly determine whether
230 * initialization is complete, and decide to trigger some immediate treatment,
231 * to launch asynchronous initialization or to bailout.
232 *
233 * Note that this attribute does not indicate that initialization has succeeded.
234 *
235 * @return |true| if the search service is now initialized, |false| if
236 * initialization has not been triggered yet.
237 */
238 readonly attribute bool isInitialized;
239
240 /**
241 * Adds a new search engine from the file at the supplied URI, optionally
242 * asking the user for confirmation first. If a confirmation dialog is
243 * shown, it will offer the option to begin using the newly added engine
244 * right away.
245 *
246 * @param engineURL
247 * The URL to the search engine's description file.
248 *
249 * @param dataType
250 * An integer representing the plugin file format. Must be one
251 * of the supported search engine data types defined above.
252 *
253 * @param iconURL
254 * A URL string to an icon file to be used as the search engine's
255 * icon. This value may be overridden by an icon specified in the
256 * engine description file.
257 *
258 * @param confirm
259 * A boolean value indicating whether the user should be asked for
260 * confirmation before this engine is added to the list. If this
261 * value is false, the engine will be added to the list upon successful
262 * load, but it will not be selected as the current engine.
263 *
264 * @param callback
265 * A nsISearchInstallCallback that will be notified when the
266 * addition is complete, or if the addition fails. It will not be
267 * called if addEngine throws an exception.
268 *
269 * @throws NS_ERROR_FAILURE if the type is invalid, or if the description
270 * file cannot be successfully loaded.
271 */
272 void addEngine(in AString engineURL, in long dataType, in AString iconURL,
273 in boolean confirm, [optional] in nsISearchInstallCallback callback);
274
275 /**
276 * Adds a new search engine, without asking the user for confirmation and
277 * without starting to use it right away.
278 *
279 * @param name
280 * The search engine's name. Must be unique. Must not be null.
281 *
282 * @param iconURL
283 * Optional: A URL string pointing to the icon to be used to represent
284 * the engine.
285 *
286 * @param alias
287 * Optional: A unique shortcut that can be used to retrieve the
288 * search engine.
289 *
290 * @param description
291 * Optional: a description of the search engine.
292 *
293 * @param method
294 * The HTTP request method used when submitting a search query.
295 * Must be a case insensitive value of either "get" or "post".
296 *
297 * @param url
298 * The URL to which search queries should be sent.
299 * Must not be null.
300 */
301 void addEngineWithDetails(in AString name,
302 in AString iconURL,
303 in AString alias,
304 in AString description,
305 in AString method,
306 in AString url);
307
308 /**
309 * Un-hides all engines installed in the directory corresponding to
310 * the directory service's NS_APP_SEARCH_DIR key. (i.e. the set of
311 * engines returned by getDefaultEngines)
312 */
313 void restoreDefaultEngines();
314
315 /**
316 * Returns an engine with the specified alias.
317 *
318 * @param alias
319 * The search engine's alias.
320 * @returns The corresponding nsISearchEngine object, or null if it doesn't
321 * exist.
322 */
323 nsISearchEngine getEngineByAlias(in AString alias);
324
325 /**
326 * Returns an engine with the specified name.
327 *
328 * @param aEngineName
329 * The name of the engine.
330 * @returns The corresponding nsISearchEngine object, or null if it doesn't
331 * exist.
332 */
333 nsISearchEngine getEngineByName(in AString aEngineName);
334
335 /**
336 * Returns an array of all installed search engines.
337 *
338 * @returns an array of nsISearchEngine objects.
339 */
340 void getEngines(
341 [optional] out unsigned long engineCount,
342 [retval, array, size_is(engineCount)] out nsISearchEngine engines);
343
344 /**
345 * Returns an array of all installed search engines whose hidden attribute is
346 * false.
347 *
348 * @returns an array of nsISearchEngine objects.
349 */
350 void getVisibleEngines(
351 [optional] out unsigned long engineCount,
352 [retval, array, size_is(engineCount)] out nsISearchEngine engines);
353
354 /**
355 * Returns an array of all default search engines. This includes all loaded
356 * engines that aren't in the user's profile directory
357 * (NS_APP_USER_SEARCH_DIR).
358 *
359 * @returns an array of nsISearchEngine objects.
360 */
361 void getDefaultEngines(
362 [optional] out unsigned long engineCount,
363 [retval, array, size_is(engineCount)] out nsISearchEngine engines);
364
365 /**
366 * Moves a visible search engine.
367 *
368 * @param engine
369 * The engine to move.
370 * @param newIndex
371 * The engine's new index in the set of visible engines.
372 *
373 * @throws NS_ERROR_FAILURE if newIndex is out of bounds, or if engine is
374 * hidden.
375 */
376 void moveEngine(in nsISearchEngine engine, in long newIndex);
377
378 /**
379 * Removes the search engine. If the search engine is installed in a global
380 * location, this will just hide the engine. If the engine is in the user's
381 * profile directory, it will be removed from disk.
382 *
383 * @param engine
384 * The engine to remove.
385 */
386 void removeEngine(in nsISearchEngine engine);
387
388 /**
389 * The default search engine. Returns the first visible engine if the default
390 * engine is hidden. May be null if there are no visible search engines.
391 */
392 attribute nsISearchEngine defaultEngine;
393
394 /**
395 * The currently active search engine. May be null if there are no visible
396 * search engines.
397 */
398 attribute nsISearchEngine currentEngine;
399 };
400
401 %{ C++
402 /**
403 * The observer topic to listen to for actions performed on installed
404 * search engines.
405 */
406 #define SEARCH_ENGINE_TOPIC "browser-search-engine-modified"
407
408 /**
409 * Sent when an engine is removed from the data store.
410 */
411 #define SEARCH_ENGINE_REMOVED "engine-removed"
412
413 /**
414 * Sent when an engine is changed. This includes when the engine's "hidden"
415 * property is changed.
416 */
417 #define SEARCH_ENGINE_CHANGED "engine-changed"
418
419 /**
420 * Sent when an engine is added to the list of available engines.
421 */
422 #define SEARCH_ENGINE_ADDED "engine-added"
423
424 /**
425 * Sent when a search engine being installed from a remote plugin description
426 * file is completely loaded. This is used internally by the search service as
427 * an indication of when the engine can be added to the internal store, and
428 * therefore should not be used to detect engine availability. It is always
429 * followed by an "added" notification.
430 */
431 #define SEARCH_ENGINE_LOADED "engine-loaded"
432
433 /**
434 * Sent when the "current" engine is changed.
435 */
436 #define SEARCH_ENGINE_CURRENT "engine-current";
437
438 /**
439 * Sent when the "default" engine is changed.
440 */
441 #define SEARCH_ENGINE_DEFAULT "engine-default";
442
443
444
445 %}

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial