1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/base/public/nsIBrowserSearchService.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,445 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#include "nsISupports.idl"
1.9 +
1.10 +interface nsIURI;
1.11 +interface nsIInputStream;
1.12 +
1.13 +[scriptable, uuid(5799251f-5b55-4df7-a9e7-0c27812c469a)]
1.14 +interface nsISearchSubmission : nsISupports
1.15 +{
1.16 + /**
1.17 + * The POST data associated with a search submission, wrapped in a MIME
1.18 + * input stream. May be null.
1.19 + */
1.20 + readonly attribute nsIInputStream postData;
1.21 +
1.22 + /**
1.23 + * The URI to submit a search to.
1.24 + */
1.25 + readonly attribute nsIURI uri;
1.26 +};
1.27 +
1.28 +[scriptable, uuid(77de6680-57ec-4105-a183-cc7cf7e84b09)]
1.29 +interface nsISearchEngine : nsISupports
1.30 +{
1.31 + /**
1.32 + * Gets a nsISearchSubmission object that contains information about what to
1.33 + * send to the search engine, including the URI and postData, if applicable.
1.34 + *
1.35 + * @param data
1.36 + * Data to add to the submission object.
1.37 + * i.e. the search terms.
1.38 + *
1.39 + * @param responseType [optional]
1.40 + * The MIME type that we'd like to receive in response
1.41 + * to this submission. If null, will default to "text/html".
1.42 + *
1.43 + * @param purpose [optional]
1.44 + * A string meant to indicate the context of the search request. This
1.45 + * allows the search service to provide a different nsISearchSubmission
1.46 + * depending on e.g. where the search is triggered in the UI.
1.47 + *
1.48 + * @returns A nsISearchSubmission object that contains information about what
1.49 + * to send to the search engine. If no submission can be
1.50 + * obtained for the given responseType, returns null.
1.51 + */
1.52 + nsISearchSubmission getSubmission(in AString data,
1.53 + [optional] in AString responseType,
1.54 + [optional] in AString purpose);
1.55 +
1.56 + /**
1.57 + * Adds a parameter to the search engine's submission data. This should only
1.58 + * be called on engines created via addEngineWithDetails.
1.59 + *
1.60 + * @param name
1.61 + * The parameter's name. Must not be null.
1.62 + *
1.63 + * @param value
1.64 + * The value to pass. If value is "{searchTerms}", it will be
1.65 + * substituted with the user-entered data when retrieving the
1.66 + * submission. Must not be null.
1.67 + *
1.68 + * @param responseType
1.69 + * Since an engine can have several different request URLs,
1.70 + * differentiated by response types, this parameter selects
1.71 + * a request to add parameters to. If null, will default
1.72 + * to "text/html"
1.73 + *
1.74 + * @throws NS_ERROR_FAILURE if the search engine is read-only.
1.75 + * @throws NS_ERROR_INVALID_ARG if name or value are null.
1.76 + */
1.77 + void addParam(in AString name, in AString value, in AString responseType);
1.78 +
1.79 + /**
1.80 + * Determines whether the engine can return responses in the given
1.81 + * MIME type. Returns true if the engine spec has a URL with the
1.82 + * given responseType, false otherwise.
1.83 + *
1.84 + * @param responseType
1.85 + * The MIME type to check for
1.86 + */
1.87 + boolean supportsResponseType(in AString responseType);
1.88 +
1.89 + /**
1.90 + * Returns a string with the URL to an engine's icon matching both width and
1.91 + * height. Returns null if icon with specified dimensions is not found.
1.92 + *
1.93 + * @param width
1.94 + * Width of the requested icon.
1.95 + * @param height
1.96 + * Height of the requested icon.
1.97 + */
1.98 + AString getIconURLBySize(in long width, in long height);
1.99 +
1.100 + /**
1.101 + * Gets an array of all available icons. Each entry is an object with
1.102 + * width, height and url properties. width and height are numeric and
1.103 + * represent the icon's dimensions. url is a string with the URL for
1.104 + * the icon.
1.105 + */
1.106 + jsval getIcons();
1.107 +
1.108 + /**
1.109 + * Supported search engine types.
1.110 + */
1.111 + const unsigned long TYPE_MOZSEARCH = 1;
1.112 + const unsigned long TYPE_SHERLOCK = 2;
1.113 + const unsigned long TYPE_OPENSEARCH = 3;
1.114 +
1.115 + /**
1.116 + * Supported search engine data types.
1.117 + */
1.118 + const unsigned long DATA_XML = 1;
1.119 + const unsigned long DATA_TEXT = 2;
1.120 +
1.121 + /**
1.122 + * An optional shortcut alias for the engine.
1.123 + * When non-null, this is a unique identifier.
1.124 + */
1.125 + attribute AString alias;
1.126 +
1.127 + /**
1.128 + * A text description describing the engine.
1.129 + */
1.130 + readonly attribute AString description;
1.131 +
1.132 + /**
1.133 + * Whether the engine should be hidden from the user.
1.134 + */
1.135 + attribute boolean hidden;
1.136 +
1.137 + /**
1.138 + * A nsIURI corresponding to the engine's icon, stored locally. May be null.
1.139 + */
1.140 + readonly attribute nsIURI iconURI;
1.141 +
1.142 + /**
1.143 + * The display name of the search engine. This is a unique identifier.
1.144 + */
1.145 + readonly attribute AString name;
1.146 +
1.147 + /**
1.148 + * A URL string pointing to the engine's search form.
1.149 + */
1.150 + readonly attribute AString searchForm;
1.151 +
1.152 + /**
1.153 + * The search engine type.
1.154 + */
1.155 + readonly attribute long type;
1.156 +
1.157 + /**
1.158 + * An optional unique identifier for this search engine within the context of
1.159 + * the distribution, as provided by the distributing entity.
1.160 + */
1.161 + readonly attribute AString identifier;
1.162 +
1.163 + /**
1.164 + * Gets a string representing the hostname from which search results for a
1.165 + * given responseType are returned, minus the leading "www." (if present).
1.166 + * This can be specified as an url attribute in the engine description file,
1.167 + * but will default to host from the <Url>'s template otherwise.
1.168 + *
1.169 + * @param responseType [optional]
1.170 + * The MIME type to get resultDomain for. Defaults to "text/html".
1.171 + *
1.172 + * @return the resultDomain for the given responseType.
1.173 + */
1.174 + AString getResultDomain([optional] in AString responseType);
1.175 +};
1.176 +
1.177 +[scriptable, uuid(9fc39136-f08b-46d3-b232-96f4b7b0e235)]
1.178 +interface nsISearchInstallCallback : nsISupports
1.179 +{
1.180 + const unsigned long ERROR_UNKNOWN_FAILURE = 0x1;
1.181 + const unsigned long ERROR_DUPLICATE_ENGINE = 0x2;
1.182 +
1.183 + /**
1.184 + * Called to indicate that the engine addition process succeeded.
1.185 + *
1.186 + * @param engine
1.187 + * The nsISearchEngine object that was added (will not be null).
1.188 + */
1.189 + void onSuccess(in nsISearchEngine engine);
1.190 +
1.191 + /**
1.192 + * Called to indicate that the engine addition process failed.
1.193 + *
1.194 + * @param errorCode
1.195 + * One of the ERROR_* values described above indicating the cause of
1.196 + * the failure.
1.197 + */
1.198 + void onError(in unsigned long errorCode);
1.199 +};
1.200 +
1.201 +/**
1.202 + * Callback for asynchronous initialization of nsIBrowserSearchService
1.203 + */
1.204 +[scriptable, function, uuid(02256156-16e4-47f1-9979-76ff98ceb590)]
1.205 +interface nsIBrowserSearchInitObserver : nsISupports
1.206 +{
1.207 + /**
1.208 + * Called once initialization of the browser search service is complete.
1.209 + *
1.210 + * @param aStatus The status of that service.
1.211 + */
1.212 + void onInitComplete(in nsresult aStatus);
1.213 +};
1.214 +
1.215 +[scriptable, uuid(939d74a4-5b01-463c-80c7-4301f0c0f9ef)]
1.216 +interface nsIBrowserSearchService : nsISupports
1.217 +{
1.218 + /**
1.219 + * Start asynchronous initialization.
1.220 + *
1.221 + * The callback is triggered once initialization is complete, which may be
1.222 + * immediately, if initialization has already been completed by some previous
1.223 + * call to this method. The callback is always invoked asynchronously.
1.224 + *
1.225 + * @param aObserver An optional object observing the end of initialization.
1.226 + */
1.227 + void init([optional] in nsIBrowserSearchInitObserver aObserver);
1.228 +
1.229 + /**
1.230 + * Determine whether initialization has been completed.
1.231 + *
1.232 + * Clients of the service can use this attribute to quickly determine whether
1.233 + * initialization is complete, and decide to trigger some immediate treatment,
1.234 + * to launch asynchronous initialization or to bailout.
1.235 + *
1.236 + * Note that this attribute does not indicate that initialization has succeeded.
1.237 + *
1.238 + * @return |true| if the search service is now initialized, |false| if
1.239 + * initialization has not been triggered yet.
1.240 + */
1.241 + readonly attribute bool isInitialized;
1.242 +
1.243 + /**
1.244 + * Adds a new search engine from the file at the supplied URI, optionally
1.245 + * asking the user for confirmation first. If a confirmation dialog is
1.246 + * shown, it will offer the option to begin using the newly added engine
1.247 + * right away.
1.248 + *
1.249 + * @param engineURL
1.250 + * The URL to the search engine's description file.
1.251 + *
1.252 + * @param dataType
1.253 + * An integer representing the plugin file format. Must be one
1.254 + * of the supported search engine data types defined above.
1.255 + *
1.256 + * @param iconURL
1.257 + * A URL string to an icon file to be used as the search engine's
1.258 + * icon. This value may be overridden by an icon specified in the
1.259 + * engine description file.
1.260 + *
1.261 + * @param confirm
1.262 + * A boolean value indicating whether the user should be asked for
1.263 + * confirmation before this engine is added to the list. If this
1.264 + * value is false, the engine will be added to the list upon successful
1.265 + * load, but it will not be selected as the current engine.
1.266 + *
1.267 + * @param callback
1.268 + * A nsISearchInstallCallback that will be notified when the
1.269 + * addition is complete, or if the addition fails. It will not be
1.270 + * called if addEngine throws an exception.
1.271 + *
1.272 + * @throws NS_ERROR_FAILURE if the type is invalid, or if the description
1.273 + * file cannot be successfully loaded.
1.274 + */
1.275 + void addEngine(in AString engineURL, in long dataType, in AString iconURL,
1.276 + in boolean confirm, [optional] in nsISearchInstallCallback callback);
1.277 +
1.278 + /**
1.279 + * Adds a new search engine, without asking the user for confirmation and
1.280 + * without starting to use it right away.
1.281 + *
1.282 + * @param name
1.283 + * The search engine's name. Must be unique. Must not be null.
1.284 + *
1.285 + * @param iconURL
1.286 + * Optional: A URL string pointing to the icon to be used to represent
1.287 + * the engine.
1.288 + *
1.289 + * @param alias
1.290 + * Optional: A unique shortcut that can be used to retrieve the
1.291 + * search engine.
1.292 + *
1.293 + * @param description
1.294 + * Optional: a description of the search engine.
1.295 + *
1.296 + * @param method
1.297 + * The HTTP request method used when submitting a search query.
1.298 + * Must be a case insensitive value of either "get" or "post".
1.299 + *
1.300 + * @param url
1.301 + * The URL to which search queries should be sent.
1.302 + * Must not be null.
1.303 + */
1.304 + void addEngineWithDetails(in AString name,
1.305 + in AString iconURL,
1.306 + in AString alias,
1.307 + in AString description,
1.308 + in AString method,
1.309 + in AString url);
1.310 +
1.311 + /**
1.312 + * Un-hides all engines installed in the directory corresponding to
1.313 + * the directory service's NS_APP_SEARCH_DIR key. (i.e. the set of
1.314 + * engines returned by getDefaultEngines)
1.315 + */
1.316 + void restoreDefaultEngines();
1.317 +
1.318 + /**
1.319 + * Returns an engine with the specified alias.
1.320 + *
1.321 + * @param alias
1.322 + * The search engine's alias.
1.323 + * @returns The corresponding nsISearchEngine object, or null if it doesn't
1.324 + * exist.
1.325 + */
1.326 + nsISearchEngine getEngineByAlias(in AString alias);
1.327 +
1.328 + /**
1.329 + * Returns an engine with the specified name.
1.330 + *
1.331 + * @param aEngineName
1.332 + * The name of the engine.
1.333 + * @returns The corresponding nsISearchEngine object, or null if it doesn't
1.334 + * exist.
1.335 + */
1.336 + nsISearchEngine getEngineByName(in AString aEngineName);
1.337 +
1.338 + /**
1.339 + * Returns an array of all installed search engines.
1.340 + *
1.341 + * @returns an array of nsISearchEngine objects.
1.342 + */
1.343 + void getEngines(
1.344 + [optional] out unsigned long engineCount,
1.345 + [retval, array, size_is(engineCount)] out nsISearchEngine engines);
1.346 +
1.347 + /**
1.348 + * Returns an array of all installed search engines whose hidden attribute is
1.349 + * false.
1.350 + *
1.351 + * @returns an array of nsISearchEngine objects.
1.352 + */
1.353 + void getVisibleEngines(
1.354 + [optional] out unsigned long engineCount,
1.355 + [retval, array, size_is(engineCount)] out nsISearchEngine engines);
1.356 +
1.357 + /**
1.358 + * Returns an array of all default search engines. This includes all loaded
1.359 + * engines that aren't in the user's profile directory
1.360 + * (NS_APP_USER_SEARCH_DIR).
1.361 + *
1.362 + * @returns an array of nsISearchEngine objects.
1.363 + */
1.364 + void getDefaultEngines(
1.365 + [optional] out unsigned long engineCount,
1.366 + [retval, array, size_is(engineCount)] out nsISearchEngine engines);
1.367 +
1.368 + /**
1.369 + * Moves a visible search engine.
1.370 + *
1.371 + * @param engine
1.372 + * The engine to move.
1.373 + * @param newIndex
1.374 + * The engine's new index in the set of visible engines.
1.375 + *
1.376 + * @throws NS_ERROR_FAILURE if newIndex is out of bounds, or if engine is
1.377 + * hidden.
1.378 + */
1.379 + void moveEngine(in nsISearchEngine engine, in long newIndex);
1.380 +
1.381 + /**
1.382 + * Removes the search engine. If the search engine is installed in a global
1.383 + * location, this will just hide the engine. If the engine is in the user's
1.384 + * profile directory, it will be removed from disk.
1.385 + *
1.386 + * @param engine
1.387 + * The engine to remove.
1.388 + */
1.389 + void removeEngine(in nsISearchEngine engine);
1.390 +
1.391 + /**
1.392 + * The default search engine. Returns the first visible engine if the default
1.393 + * engine is hidden. May be null if there are no visible search engines.
1.394 + */
1.395 + attribute nsISearchEngine defaultEngine;
1.396 +
1.397 + /**
1.398 + * The currently active search engine. May be null if there are no visible
1.399 + * search engines.
1.400 + */
1.401 + attribute nsISearchEngine currentEngine;
1.402 +};
1.403 +
1.404 +%{ C++
1.405 +/**
1.406 + * The observer topic to listen to for actions performed on installed
1.407 + * search engines.
1.408 + */
1.409 +#define SEARCH_ENGINE_TOPIC "browser-search-engine-modified"
1.410 +
1.411 +/**
1.412 + * Sent when an engine is removed from the data store.
1.413 + */
1.414 +#define SEARCH_ENGINE_REMOVED "engine-removed"
1.415 +
1.416 +/**
1.417 + * Sent when an engine is changed. This includes when the engine's "hidden"
1.418 + * property is changed.
1.419 + */
1.420 +#define SEARCH_ENGINE_CHANGED "engine-changed"
1.421 +
1.422 +/**
1.423 + * Sent when an engine is added to the list of available engines.
1.424 + */
1.425 +#define SEARCH_ENGINE_ADDED "engine-added"
1.426 +
1.427 +/**
1.428 + * Sent when a search engine being installed from a remote plugin description
1.429 + * file is completely loaded. This is used internally by the search service as
1.430 + * an indication of when the engine can be added to the internal store, and
1.431 + * therefore should not be used to detect engine availability. It is always
1.432 + * followed by an "added" notification.
1.433 + */
1.434 +#define SEARCH_ENGINE_LOADED "engine-loaded"
1.435 +
1.436 +/**
1.437 + * Sent when the "current" engine is changed.
1.438 + */
1.439 +#define SEARCH_ENGINE_CURRENT "engine-current";
1.440 +
1.441 +/**
1.442 + * Sent when the "default" engine is changed.
1.443 + */
1.444 +#define SEARCH_ENGINE_DEFAULT "engine-default";
1.445 +
1.446 +
1.447 +
1.448 +%}
