2007-03-22 10:30:00 -07:00
|
|
|
/* ***** BEGIN LICENSE BLOCK *****
|
|
|
|
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
|
|
|
|
*
|
|
|
|
* The contents of this file are subject to the Mozilla Public License Version
|
|
|
|
* 1.1 (the "License"); you may not use this file except in compliance with
|
|
|
|
* the License. You may obtain a copy of the License at
|
|
|
|
* http://www.mozilla.org/MPL/
|
|
|
|
*
|
|
|
|
* Software distributed under the License is distributed on an "AS IS" basis,
|
|
|
|
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
|
|
|
|
* for the specific language governing rights and limitations under the
|
|
|
|
* License.
|
|
|
|
*
|
|
|
|
* The Original Code is the Browser Search Service.
|
|
|
|
*
|
|
|
|
* The Initial Developer of the Original Code is
|
|
|
|
* Google Inc.
|
|
|
|
* Portions created by the Initial Developer are Copyright (C) 2005-2006
|
|
|
|
* the Initial Developer. All Rights Reserved.
|
|
|
|
*
|
|
|
|
* Contributor(s):
|
|
|
|
* Ben Goodger <beng@google.com> (Original author)
|
|
|
|
* Gavin Sharp <gavin@gavinsharp.com>
|
|
|
|
* Joe Hughes <joe@retrovirus.com>
|
|
|
|
* Pamela Greene <pamg.bugs@gmail.com>
|
|
|
|
*
|
|
|
|
* Alternatively, the contents of this file may be used under the terms of
|
|
|
|
* either the GNU General Public License Version 2 or later (the "GPL"), or
|
|
|
|
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
|
|
|
|
* in which case the provisions of the GPL or the LGPL are applicable instead
|
|
|
|
* of those above. If you wish to allow use of your version of this file only
|
|
|
|
* under the terms of either the GPL or the LGPL, and not to allow others to
|
|
|
|
* use your version of this file under the terms of the MPL, indicate your
|
|
|
|
* decision by deleting the provisions above and replace them with the notice
|
|
|
|
* and other provisions required by the GPL or the LGPL. If you do not delete
|
|
|
|
* the provisions above, a recipient may use your version of this file under
|
|
|
|
* the terms of any one of the MPL, the GPL or the LGPL.
|
|
|
|
*
|
|
|
|
* ***** END LICENSE BLOCK ***** */
|
|
|
|
|
|
|
|
#include "nsISupports.idl"
|
|
|
|
|
|
|
|
interface nsIURI;
|
|
|
|
interface nsIInputStream;
|
|
|
|
|
|
|
|
[scriptable, uuid(58e4f602-a7c8-4cd1-9dca-716705e826ef)]
|
|
|
|
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(803e510b-4b27-4ba2-a16d-bb5fa953c166)]
|
|
|
|
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 data
|
|
|
|
* Data to add to the submission object.
|
|
|
|
* 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
|
|
|
|
* to send to the search engine. If no submission can be
|
|
|
|
* obtained for the given responseType, returns null.
|
|
|
|
*/
|
|
|
|
nsISearchSubmission getSubmission(in AString data, in AString responseType);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Adds a parameter to the search engine's submission data. This should only
|
|
|
|
* be called on engines 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.
|
|
|
|
*
|
|
|
|
* @param responseType
|
|
|
|
* Since an engine can have several different request URLs,
|
|
|
|
* differentiated by response types, this parameter selects
|
|
|
|
* a request to add parameters to. If null, will default
|
|
|
|
* to "text/html"
|
|
|
|
*
|
|
|
|
* @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, in AString responseType);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* 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);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Supported search engine types.
|
|
|
|
*/
|
|
|
|
const unsigned long TYPE_MOZSEARCH = 1;
|
|
|
|
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. This is a unique identifier.
|
|
|
|
*/
|
|
|
|
attribute AString alias;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* A text description describing the engine.
|
|
|
|
*/
|
|
|
|
readonly attribute AString description;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Whether the engine should be hidden from the user.
|
|
|
|
*/
|
|
|
|
attribute boolean hidden;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* A nsIURI corresponding to the engine's icon, stored locally. May be null.
|
|
|
|
*/
|
|
|
|
readonly attribute nsIURI iconURI;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* The display name of the search engine. This is a unique identifier.
|
|
|
|
*/
|
|
|
|
readonly attribute AString name;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* A URL string pointing to the engine's search form.
|
|
|
|
*/
|
|
|
|
readonly attribute AString searchForm;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* The search engine type.
|
|
|
|
*/
|
|
|
|
readonly attribute long type;
|
|
|
|
|
|
|
|
};
|
|
|
|
|
2007-09-11 09:07:11 -07:00
|
|
|
[scriptable, uuid(8307b8f2-08ea-45b8-96bf-b1dc7688fe3b)]
|
2007-03-22 10:30:00 -07:00
|
|
|
interface nsIBrowserSearchService : nsISupports
|
|
|
|
{
|
|
|
|
/**
|
|
|
|
* Adds a new search engine from the file at the supplied URI, optionally
|
|
|
|
* asking the user for confirmation first. If a confirmation dialog is
|
|
|
|
* shown, it will offer the option to begin using the newly added engine
|
|
|
|
* right away; if no confirmation dialog is shown, the new engine will be
|
|
|
|
* used right away automatically.
|
|
|
|
*
|
|
|
|
* @param engineURL
|
|
|
|
* The URL to the search engine's description file.
|
|
|
|
*
|
|
|
|
* @param dataType
|
|
|
|
* An integer representing the plugin file format. Must be one
|
|
|
|
* of the supported search engine data types defined above.
|
|
|
|
*
|
|
|
|
* @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.
|
|
|
|
*
|
|
|
|
* @param confirm
|
|
|
|
* A boolean value indicating whether the user should be asked for
|
|
|
|
* confirmation before this engine is added to the list. If this
|
|
|
|
* value is false, the engine will be added to the list upon successful
|
|
|
|
* load, but it will not be selected as the current engine.
|
|
|
|
*
|
|
|
|
* @throws NS_ERROR_FAILURE if the type is invalid, or if the description
|
|
|
|
* file cannot be successfully loaded.
|
|
|
|
*/
|
|
|
|
void addEngine(in AString engineURL, in long dataType, in AString iconURL,
|
|
|
|
in boolean confirm);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Adds a new search engine, without asking the user for confirmation and
|
|
|
|
* without starting to use it right away.
|
|
|
|
*
|
|
|
|
* @param name
|
|
|
|
* The search engine's name. Must be unique. Must not be null.
|
|
|
|
*
|
|
|
|
* @param iconURL
|
|
|
|
* 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(in AString name,
|
|
|
|
in AString iconURL,
|
|
|
|
in AString alias,
|
|
|
|
in AString description,
|
|
|
|
in AString method,
|
|
|
|
in AString url);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Un-hides all engines installed in the directory corresponding to
|
|
|
|
* the directory service's NS_APP_SEARCH_DIR key. (i.e. the set of
|
|
|
|
* engines returned by getDefaultEngines)
|
|
|
|
*/
|
|
|
|
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.
|
|
|
|
*/
|
|
|
|
nsISearchEngine 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 array of all installed search engines.
|
|
|
|
*
|
|
|
|
* @returns an array of nsISearchEngine objects.
|
|
|
|
*/
|
|
|
|
void getEngines(
|
|
|
|
out unsigned long engineCount,
|
|
|
|
[retval, array, size_is(engineCount)] out nsISearchEngine engines);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* 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);
|
|
|
|
|
|
|
|
/**
|
2007-05-04 08:48:08 -07:00
|
|
|
* Returns an array of all default search engines. This includes all loaded
|
|
|
|
* engines that aren't in the user's profile directory
|
|
|
|
* (NS_APP_USER_SEARCH_DIR).
|
2007-03-22 10:30:00 -07:00
|
|
|
*
|
|
|
|
* @returns an array of nsISearchEngine objects.
|
|
|
|
*/
|
|
|
|
void getDefaultEngines(
|
|
|
|
out unsigned long engineCount,
|
|
|
|
[retval, array, size_is(engineCount)] out nsISearchEngine engines);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* 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.
|
|
|
|
*/
|
|
|
|
void 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.
|
|
|
|
*/
|
|
|
|
void removeEngine(in nsISearchEngine engine);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* The default search engine. May be null if there are no visible
|
|
|
|
* search engines installed.
|
|
|
|
*/
|
|
|
|
readonly attribute nsISearchEngine defaultEngine;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* The currently active search engine. May be null if there are no visible
|
|
|
|
* search engines installed.
|
|
|
|
*/
|
|
|
|
attribute nsISearchEngine currentEngine;
|
|
|
|
|
|
|
|
};
|
|
|
|
|
|
|
|
%{ C++
|
|
|
|
/**
|
|
|
|
* The observer topic to listen to for actions performed on installed
|
|
|
|
* search engines.
|
|
|
|
*/
|
|
|
|
#define SEARCH_ENGINE_TOPIC "browser-search-engine-modified"
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sent when an engine is removed from the data store.
|
|
|
|
*/
|
|
|
|
#define SEARCH_ENGINE_REMOVED "engine-removed"
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sent when an engine is changed. This includes when the engine's "hidden"
|
|
|
|
* property is changed.
|
|
|
|
*/
|
|
|
|
#define SEARCH_ENGINE_CHANGED "engine-changed"
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sent when an engine is added to the list of available engines.
|
|
|
|
*/
|
|
|
|
#define SEARCH_ENGINE_ADDED "engine-added"
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sent when a search engine being installed from a remote plugin description
|
|
|
|
* file is completely loaded. This is used internally by the search service as
|
|
|
|
* an indication of when the engine can be added to the internal store, and
|
|
|
|
* therefore should not be used to detect engine availability. It is always
|
|
|
|
* followed by an "added" notification.
|
|
|
|
*/
|
|
|
|
#define SEARCH_ENGINE_LOADED "engine-loaded"
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sent when the "current" engine is changed.
|
|
|
|
*/
|
|
|
|
#define SEARCH_ENGINE_CURRENT "engine-current";
|
|
|
|
|
|
|
|
%}
|