The Tor Browser / file revision

 # 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/.

 const Ci = Components.interfaces;

 const Cc = Components.classes;

 const Cr = Components.results;

 const Cu = Components.utils;

 Components.utils.import("resource://gre/modules/XPCOMUtils.jsm");

 Components.utils.import("resource://gre/modules/Services.jsm");

 Components.utils.import("resource://gre/modules/Promise.jsm");

 XPCOMUtils.defineLazyModuleGetter(this, "AsyncShutdown",

   "resource://gre/modules/AsyncShutdown.jsm");

 XPCOMUtils.defineLazyModuleGetter(this, "DeferredTask",

   "resource://gre/modules/DeferredTask.jsm");

 XPCOMUtils.defineLazyModuleGetter(this, "OS",

   "resource://gre/modules/osfile.jsm");

 XPCOMUtils.defineLazyModuleGetter(this, "Task",

   "resource://gre/modules/Task.jsm");

 XPCOMUtils.defineLazyModuleGetter(this, "TelemetryStopwatch",

   "resource://gre/modules/TelemetryStopwatch.jsm");

 // A text encoder to UTF8, used whenever we commit the

 // engine metadata to disk.

 XPCOMUtils.defineLazyGetter(this, "gEncoder",

                             function() {

                               return new TextEncoder();

                             });

 const PERMS_FILE      = 0644;

 const PERMS_DIRECTORY = 0755;

 const MODE_RDONLY   = 0x01;

 const MODE_WRONLY   = 0x02;

 const MODE_CREATE   = 0x08;

 const MODE_APPEND   = 0x10;

 const MODE_TRUNCATE = 0x20;

 // Directory service keys

 const NS_APP_SEARCH_DIR_LIST  = "SrchPluginsDL";

 const NS_APP_USER_SEARCH_DIR  = "UsrSrchPlugns";

 const NS_APP_SEARCH_DIR       = "SrchPlugns";

 const NS_APP_USER_PROFILE_50_DIR = "ProfD";

 // Search engine "locations". If this list is changed, be sure to update

 // the engine's _isDefault function accordingly.

 const SEARCH_APP_DIR = 1;

 const SEARCH_PROFILE_DIR = 2;

 const SEARCH_IN_EXTENSION = 3;

 const SEARCH_JAR = 4;

 // See documentation in nsIBrowserSearchService.idl.

 const SEARCH_ENGINE_TOPIC        = "browser-search-engine-modified";

 const QUIT_APPLICATION_TOPIC     = "quit-application";

 const SEARCH_ENGINE_REMOVED      = "engine-removed";

 const SEARCH_ENGINE_ADDED        = "engine-added";

 const SEARCH_ENGINE_CHANGED      = "engine-changed";

 const SEARCH_ENGINE_LOADED       = "engine-loaded";

 const SEARCH_ENGINE_CURRENT      = "engine-current";

 const SEARCH_ENGINE_DEFAULT      = "engine-default";

 // The following constants are left undocumented in nsIBrowserSearchService.idl

 // For the moment, they are meant for testing/debugging purposes only.

 /**

  * Topic used for events involving the service itself.

  */

 const SEARCH_SERVICE_TOPIC       = "browser-search-service";

 /**

  * Sent whenever metadata is fully written to disk.

  */

 const SEARCH_SERVICE_METADATA_WRITTEN  = "write-metadata-to-disk-complete";

 /**

  * Sent whenever the cache is fully written to disk.

  */

 const SEARCH_SERVICE_CACHE_WRITTEN  = "write-cache-to-disk-complete";

 const SEARCH_TYPE_MOZSEARCH      = Ci.nsISearchEngine.TYPE_MOZSEARCH;

 const SEARCH_TYPE_OPENSEARCH     = Ci.nsISearchEngine.TYPE_OPENSEARCH;

 const SEARCH_TYPE_SHERLOCK       = Ci.nsISearchEngine.TYPE_SHERLOCK;

 const SEARCH_DATA_XML            = Ci.nsISearchEngine.DATA_XML;

 const SEARCH_DATA_TEXT           = Ci.nsISearchEngine.DATA_TEXT;

 // Delay for lazy serialization (ms)

 const LAZY_SERIALIZE_DELAY = 100;

 // Delay for batching invalidation of the JSON cache (ms)

 const CACHE_INVALIDATION_DELAY = 1000;

 // Current cache version. This should be incremented if the format of the cache

 // file is modified.

 const CACHE_VERSION = 7;

 const ICON_DATAURL_PREFIX = "data:image/x-icon;base64,";

 const NEW_LINES = /(\r\n|\r|\n)/;

 // Set an arbitrary cap on the maximum icon size. Without this, large icons can

 // cause big delays when loading them at startup.

 const MAX_ICON_SIZE   = 10000;

 // Default charset to use for sending search parameters. ISO-8859-1 is used to

 // match previous nsInternetSearchService behavior.

 const DEFAULT_QUERY_CHARSET = "ISO-8859-1";

 const SEARCH_BUNDLE = "chrome://global/locale/search/search.properties";

 const BRAND_BUNDLE = "chrome://branding/locale/brand.properties";

 const OPENSEARCH_NS_10  = "http://a9.com/-/spec/opensearch/1.0/";

 const OPENSEARCH_NS_11  = "http://a9.com/-/spec/opensearch/1.1/";

 // Although the specification at http://opensearch.a9.com/spec/1.1/description/

 // gives the namespace names defined above, many existing OpenSearch engines

 // are using the following versions.  We therefore allow either.

 const OPENSEARCH_NAMESPACES = [

   OPENSEARCH_NS_11, OPENSEARCH_NS_10,

   "http://a9.com/-/spec/opensearchdescription/1.1/",

   "http://a9.com/-/spec/opensearchdescription/1.0/"

 ];

 const OPENSEARCH_LOCALNAME = "OpenSearchDescription";

 const MOZSEARCH_NS_10     = "http://www.mozilla.org/2006/browser/search/";

 const MOZSEARCH_LOCALNAME = "SearchPlugin";

 const URLTYPE_SUGGEST_JSON = "application/x-suggestions+json";

 const URLTYPE_SEARCH_HTML  = "text/html";

 const URLTYPE_OPENSEARCH   = "application/opensearchdescription+xml";

 // Empty base document used to serialize engines to file.

 const EMPTY_DOC = "<?xml version=\"1.0\"?>\n" +

                   "<" + MOZSEARCH_LOCALNAME +

                   " xmlns=\"" + MOZSEARCH_NS_10 + "\"" +

                   " xmlns:os=\"" + OPENSEARCH_NS_11 + "\"" +

                   "/>";

 const BROWSER_SEARCH_PREF = "browser.search.";

 const USER_DEFINED = "{searchTerms}";

 // Custom search parameters

 #ifdef MOZ_OFFICIAL_BRANDING

 const MOZ_OFFICIAL = "official";

 #else

 const MOZ_OFFICIAL = "unofficial";

 #endif

 #expand const MOZ_DISTRIBUTION_ID = __MOZ_DISTRIBUTION_ID__;

 const MOZ_PARAM_LOCALE         = /\{moz:locale\}/g;

 const MOZ_PARAM_DIST_ID        = /\{moz:distributionID\}/g;

 const MOZ_PARAM_OFFICIAL       = /\{moz:official\}/g;

 // Supported OpenSearch parameters

 // See http://opensearch.a9.com/spec/1.1/querysyntax/#core

 const OS_PARAM_USER_DEFINED    = /\{searchTerms\??\}/g;

 const OS_PARAM_INPUT_ENCODING  = /\{inputEncoding\??\}/g;

 const OS_PARAM_LANGUAGE        = /\{language\??\}/g;

 const OS_PARAM_OUTPUT_ENCODING = /\{outputEncoding\??\}/g;

 // Default values

 const OS_PARAM_LANGUAGE_DEF         = "*";

 const OS_PARAM_OUTPUT_ENCODING_DEF  = "UTF-8";

 const OS_PARAM_INPUT_ENCODING_DEF   = "UTF-8";

 // "Unsupported" OpenSearch parameters. For example, we don't support

 // page-based results, so if the engine requires that we send the "page index"

 // parameter, we'll always send "1".

 const OS_PARAM_COUNT        = /\{count\??\}/g;

 const OS_PARAM_START_INDEX  = /\{startIndex\??\}/g;

 const OS_PARAM_START_PAGE   = /\{startPage\??\}/g;

 // Default values

 const OS_PARAM_COUNT_DEF        = "20"; // 20 results

 const OS_PARAM_START_INDEX_DEF  = "1";  // start at 1st result

 const OS_PARAM_START_PAGE_DEF   = "1";  // 1st page

 // Optional parameter

 const OS_PARAM_OPTIONAL     = /\{(?:\w+:)?\w+\?\}/g;

 // A array of arrays containing parameters that we don't fully support, and

 // their default values. We will only send values for these parameters if

 // required, since our values are just really arbitrary "guesses" that should

 // give us the output we want.

 var OS_UNSUPPORTED_PARAMS = [

   [OS_PARAM_COUNT, OS_PARAM_COUNT_DEF],

   [OS_PARAM_START_INDEX, OS_PARAM_START_INDEX_DEF],

   [OS_PARAM_START_PAGE, OS_PARAM_START_PAGE_DEF],

 ];

 // The default engine update interval, in days. This is only used if an engine

 // specifies an updateURL, but not an updateInterval.

 const SEARCH_DEFAULT_UPDATE_INTERVAL = 7;

 // Returns false for whitespace-only or commented out lines in a

 // Sherlock file, true otherwise.

 function isUsefulLine(aLine) {

   return !(/^\s*($|#)/i.test(aLine));

 }

 this.__defineGetter__("FileUtils", function() {

   delete this.FileUtils;

   Components.utils.import("resource://gre/modules/FileUtils.jsm");

   return FileUtils;

 });

 this.__defineGetter__("NetUtil", function() {

   delete this.NetUtil;

   Components.utils.import("resource://gre/modules/NetUtil.jsm");

   return NetUtil;

 });

 this.__defineGetter__("gChromeReg", function() {

   delete this.gChromeReg;

   return this.gChromeReg = Cc["@mozilla.org/chrome/chrome-registry;1"].

                            getService(Ci.nsIChromeRegistry);

 });

 /**

  * Prefixed to all search debug output.

  */

 const SEARCH_LOG_PREFIX = "*** Search: ";

 /**

  * Outputs aText to the JavaScript console as well as to stdout.

  */

 function DO_LOG(aText) {

   dump(SEARCH_LOG_PREFIX + aText + "\n");

   Services.console.logStringMessage(aText);

 }

 #ifdef DEBUG

 /**

  * In debug builds, use a live, pref-based (browser.search.log) LOG function

  * to allow enabling/disabling without a restart.

  */

 function PREF_LOG(aText) {

   if (getBoolPref(BROWSER_SEARCH_PREF + "log", false))

     DO_LOG(aText);

 }

 var LOG = PREF_LOG;

 #else

 /**

  * Otherwise, don't log at all by default. This can be overridden at startup

  * by the pref, see SearchService's _init method.

  */

 var LOG = function(){};

 #endif

 /**

  * Presents an assertion dialog in non-release builds and throws.

  * @param  message

  *         A message to display

  * @param  resultCode

  *         The NS_ERROR_* value to throw.

  * @throws resultCode

  */

 function ERROR(message, resultCode) {

   NS_ASSERT(false, SEARCH_LOG_PREFIX + message);

   throw Components.Exception(message, resultCode);

 }

 /**

  * Logs the failure message (if browser.search.log is enabled) and throws.

  * @param  message

  *         A message to display

  * @param  resultCode

  *         The NS_ERROR_* value to throw.

  * @throws resultCode or NS_ERROR_INVALID_ARG if resultCode isn't specified.

  */

 function FAIL(message, resultCode) {

   LOG(message);

   throw Components.Exception(message, resultCode || Cr.NS_ERROR_INVALID_ARG);

 }

 /**

  * Truncates big blobs of (data-)URIs to console-friendly sizes

  * @param str

  *        String to tone down

  * @param len

  *        Maximum length of the string to return. Defaults to the length of a tweet.

  */

 function limitURILength(str, len) {

   len = len || 140;

   if (str.length > len)

     return str.slice(0, len) + "...";

   return str;

 }

 /**

  * Utilities for dealing with promises and Task.jsm

  */

 const TaskUtils = {

   /**

    * Add logging to a promise.

    *

    * @param {Promise} promise

    * @return {Promise} A promise behaving as |promise|, but with additional

    * logging in case of uncaught error.

    */

   captureErrors: function captureErrors(promise) {

     return promise.then(

       null,

       function onError(reason) {

         LOG("Uncaught asynchronous error: " + reason + " at\n" + reason.stack);

         throw reason;

       }

     );

   },

   /**

    * Spawn a new Task from a generator.

    *

    * This function behaves as |Task.spawn|, with the exception that it

    * adds logging in case of uncaught error. For more information, see

    * the documentation of |Task.jsm|.

    *

    * @param {generator} gen Some generator.

    * @return {Promise} A promise built from |gen|, with the same semantics

    * as |Task.spawn(gen)|.

    */

   spawn: function spawn(gen) {

     return this.captureErrors(Task.spawn(gen));

   },

   /**

    * Execute a mozIStorage statement asynchronously, wrapping the

    * result in a promise.

    *

    * @param {mozIStorageStaement} statement A statement to be executed

    * asynchronously. The semantics are the same as these of |statement.execute|.

    * @param {function*} onResult A callback, called for each successive result.

    *

    * @return {Promise} A promise, resolved successfully if |statement.execute|

    * succeeds, rejected if it fails.

    */

   executeStatement: function executeStatement(statement, onResult) {

     let deferred = Promise.defer();

     onResult = onResult || function() {};

     statement.executeAsync({

       handleResult: onResult,

       handleError: function handleError(aError) {

         deferred.reject(aError);

       },

       handleCompletion: function handleCompletion(aReason) {

         statement.finalize();

         // Note that, in case of error, deferred.reject(aError)

         // has already been called by this point, so the call to

         // |deferred.resolve| is simply ignored.

         deferred.resolve(aReason);

       }

     });

     return deferred.promise;

   }

 };

 /**

  * Ensures an assertion is met before continuing. Should be used to indicate

  * fatal errors.

  * @param  assertion

  *         An assertion that must be met

  * @param  message

  *         A message to display if the assertion is not met

  * @param  resultCode

  *         The NS_ERROR_* value to throw if the assertion is not met

  * @throws resultCode

  */

 function ENSURE_WARN(assertion, message, resultCode) {

   NS_ASSERT(assertion, SEARCH_LOG_PREFIX + message);

   if (!assertion)

     throw Components.Exception(message, resultCode);

 }

 function loadListener(aChannel, aEngine, aCallback) {

   this._channel = aChannel;

   this._bytes = [];

   this._engine = aEngine;

   this._callback = aCallback;

 }

 loadListener.prototype = {

   _callback: null,

   _channel: null,

   _countRead: 0,

   _engine: null,

   _stream: null,

   QueryInterface: function SRCH_loadQI(aIID) {

     if (aIID.equals(Ci.nsISupports)           ||

         aIID.equals(Ci.nsIRequestObserver)    ||

         aIID.equals(Ci.nsIStreamListener)     ||

         aIID.equals(Ci.nsIChannelEventSink)   ||

         aIID.equals(Ci.nsIInterfaceRequestor) ||

         // See FIXME comment below

         aIID.equals(Ci.nsIHttpEventSink)      ||

         aIID.equals(Ci.nsIProgressEventSink)  ||

         false)

       return this;

     throw Cr.NS_ERROR_NO_INTERFACE;

   },

   // nsIRequestObserver

   onStartRequest: function SRCH_loadStartR(aRequest, aContext) {

     LOG("loadListener: Starting request: " + aRequest.name);

     this._stream = Cc["@mozilla.org/binaryinputstream;1"].

                    createInstance(Ci.nsIBinaryInputStream);

   },

   onStopRequest: function SRCH_loadStopR(aRequest, aContext, aStatusCode) {

     LOG("loadListener: Stopping request: " + aRequest.name);

     var requestFailed = !Components.isSuccessCode(aStatusCode);

     if (!requestFailed && (aRequest instanceof Ci.nsIHttpChannel))

       requestFailed = !aRequest.requestSucceeded;

     if (requestFailed || this._countRead == 0) {

       LOG("loadListener: request failed!");

       // send null so the callback can deal with the failure

       this._callback(null, this._engine);

     } else

       this._callback(this._bytes, this._engine);

     this._channel = null;

     this._engine  = null;

   },

   // nsIStreamListener

   onDataAvailable: function SRCH_loadDAvailable(aRequest, aContext,

                                                 aInputStream, aOffset,

                                                 aCount) {

     this._stream.setInputStream(aInputStream);

     // Get a byte array of the data

     this._bytes = this._bytes.concat(this._stream.readByteArray(aCount));

     this._countRead += aCount;

   },

   // nsIChannelEventSink

   asyncOnChannelRedirect: function SRCH_loadCRedirect(aOldChannel, aNewChannel,

                                                       aFlags, callback) {

     this._channel = aNewChannel;

     callback.onRedirectVerifyCallback(Components.results.NS_OK);

   },

   // nsIInterfaceRequestor

   getInterface: function SRCH_load_GI(aIID) {

     return this.QueryInterface(aIID);

   },

   // FIXME: bug 253127

   // nsIHttpEventSink

   onRedirect: function (aChannel, aNewChannel) {},

   // nsIProgressEventSink

   onProgress: function (aRequest, aContext, aProgress, aProgressMax) {},

   onStatus: function (aRequest, aContext, aStatus, aStatusArg) {}

 }

 /**

  * Used to verify a given DOM node's localName and namespaceURI.

  * @param aElement

  *        The element to verify.

  * @param aLocalNameArray

  *        An array of strings to compare against aElement's localName.

  * @param aNameSpaceArray

  *        An array of strings to compare against aElement's namespaceURI.

  *

  * @returns false if aElement is null, or if its localName or namespaceURI

  *          does not match one of the elements in the aLocalNameArray or

  *          aNameSpaceArray arrays, respectively.

  * @throws NS_ERROR_INVALID_ARG if aLocalNameArray or aNameSpaceArray are null.

  */

 function checkNameSpace(aElement, aLocalNameArray, aNameSpaceArray) {

   if (!aLocalNameArray || !aNameSpaceArray)

     FAIL("missing aLocalNameArray or aNameSpaceArray for checkNameSpace");

   return (aElement                                                &&

           (aLocalNameArray.indexOf(aElement.localName)    != -1)  &&

           (aNameSpaceArray.indexOf(aElement.namespaceURI) != -1));

 }

 /**

  * Safely close a nsISafeOutputStream.

  * @param aFOS

  *        The file output stream to close.

  */

 function closeSafeOutputStream(aFOS) {

   if (aFOS instanceof Ci.nsISafeOutputStream) {

     try {

       aFOS.finish();

       return;

     } catch (e) { }

   }

   aFOS.close();

 }

 /**

  * Wrapper function for nsIIOService::newURI.

  * @param aURLSpec

  *        The URL string from which to create an nsIURI.

  * @returns an nsIURI object, or null if the creation of the URI failed.

  */

 function makeURI(aURLSpec, aCharset) {

   try {

     return NetUtil.newURI(aURLSpec, aCharset);

   } catch (ex) { }

   return null;

 }

 /**

  * Gets a directory from the directory service.

  * @param aKey

  *        The directory service key indicating the directory to get.

  */

 function getDir(aKey, aIFace) {

   if (!aKey)

     FAIL("getDir requires a directory key!");

   return Services.dirsvc.get(aKey, aIFace || Ci.nsIFile);

 }

 /**

  * The following two functions are essentially copied from

  * nsInternetSearchService. They are required for backwards compatibility.

  */

 function queryCharsetFromCode(aCode) {

   const codes = [];

   codes[0] = "macintosh";

   codes[6] = "x-mac-greek";

   codes[35] = "x-mac-turkish";

   codes[513] = "ISO-8859-1";

   codes[514] = "ISO-8859-2";

   codes[517] = "ISO-8859-5";

   codes[518] = "ISO-8859-6";

   codes[519] = "ISO-8859-7";

   codes[520] = "ISO-8859-8";

   codes[521] = "ISO-8859-9";

   codes[1280] = "windows-1252";

   codes[1281] = "windows-1250";

   codes[1282] = "windows-1251";

   codes[1283] = "windows-1253";

   codes[1284] = "windows-1254";

   codes[1285] = "windows-1255";

   codes[1286] = "windows-1256";

   codes[1536] = "us-ascii";

   codes[1584] = "GB2312";

   codes[1585] = "gbk";

   codes[1600] = "EUC-KR";

   codes[2080] = "ISO-2022-JP";

   codes[2096] = "ISO-2022-CN";

   codes[2112] = "ISO-2022-KR";

   codes[2336] = "EUC-JP";

   codes[2352] = "GB2312";

   codes[2353] = "x-euc-tw";

   codes[2368] = "EUC-KR";

   codes[2561] = "Shift_JIS";

   codes[2562] = "KOI8-R";

   codes[2563] = "Big5";

   codes[2565] = "HZ-GB-2312";

   if (codes[aCode])

     return codes[aCode];

   // Don't bother being fancy about what to return in the failure case.

   return "windows-1252";

 }

 function fileCharsetFromCode(aCode) {

   const codes = [

     "macintosh",             // 0

     "Shift_JIS",             // 1

     "Big5",                  // 2

     "EUC-KR",                // 3

     "X-MAC-ARABIC",          // 4

     "X-MAC-HEBREW",          // 5

     "X-MAC-GREEK",           // 6

     "X-MAC-CYRILLIC",        // 7

     "X-MAC-DEVANAGARI" ,     // 9

     "X-MAC-GURMUKHI",        // 10

     "X-MAC-GUJARATI",        // 11

     "X-MAC-ORIYA",           // 12

     "X-MAC-BENGALI",         // 13

     "X-MAC-TAMIL",           // 14

     "X-MAC-TELUGU",          // 15

     "X-MAC-KANNADA",         // 16

     "X-MAC-MALAYALAM",       // 17

     "X-MAC-SINHALESE",       // 18

     "X-MAC-BURMESE",         // 19

     "X-MAC-KHMER",           // 20

     "X-MAC-THAI",            // 21

     "X-MAC-LAOTIAN",         // 22

     "X-MAC-GEORGIAN",        // 23

     "X-MAC-ARMENIAN",        // 24

     "GB2312",                // 25

     "X-MAC-TIBETAN",         // 26

     "X-MAC-MONGOLIAN",       // 27

     "X-MAC-ETHIOPIC",        // 28

     "X-MAC-CENTRALEURROMAN", // 29

     "X-MAC-VIETNAMESE",      // 30

     "X-MAC-EXTARABIC"        // 31

   ];

   // Sherlock files have always defaulted to macintosh, so do that here too

   return codes[aCode] || codes[0];

 }

 /**

  * Returns a string interpretation of aBytes using aCharset, or null on

  * failure.

  */

 function bytesToString(aBytes, aCharset) {

   var converter = Cc["@mozilla.org/intl/scriptableunicodeconverter"].

                   createInstance(Ci.nsIScriptableUnicodeConverter);

   LOG("bytesToString: converting using charset: " + aCharset);

   try {

     converter.charset = aCharset;

     return converter.convertFromByteArray(aBytes, aBytes.length);

   } catch (ex) {}

   return null;

 }

 /**

  * Converts an array of bytes representing a Sherlock file into an array of

  * lines representing the useful data from the file.

  *

  * @param aBytes

  *        The array of bytes representing the Sherlock file.

  * @param aCharsetCode

  *        An integer value representing a character set code to be passed to

  *        fileCharsetFromCode, or null for the default Sherlock encoding.

  */

 function sherlockBytesToLines(aBytes, aCharsetCode) {

   // fileCharsetFromCode returns the default encoding if aCharsetCode is null

   var charset = fileCharsetFromCode(aCharsetCode);

   var dataString = bytesToString(aBytes, charset);

   if (!dataString)

     FAIL("sherlockBytesToLines: Couldn't convert byte array!", Cr.NS_ERROR_FAILURE);

   // Split the string into lines, and filter out comments and

   // whitespace-only lines

   return dataString.split(NEW_LINES).filter(isUsefulLine);

 }

 /**

  * Gets the current value of the locale.  It's possible for this preference to

  * be localized, so we have to do a little extra work here.  Similar code

  * exists in nsHttpHandler.cpp when building the UA string.

  */

 function getLocale() {

   const localePref = "general.useragent.locale";

   var locale = getLocalizedPref(localePref);

   if (locale)

     return locale;

   // Not localized

   return Services.prefs.getCharPref(localePref);

 }

 /**

  * Wrapper for nsIPrefBranch::getComplexValue.

  * @param aPrefName

  *        The name of the pref to get.

  * @returns aDefault if the requested pref doesn't exist.

  */

 function getLocalizedPref(aPrefName, aDefault) {

   const nsIPLS = Ci.nsIPrefLocalizedString;

   try {

     return Services.prefs.getComplexValue(aPrefName, nsIPLS).data;

   } catch (ex) {}

   return aDefault;

 }

 /**

  * Wrapper for nsIPrefBranch::setComplexValue.

  * @param aPrefName

  *        The name of the pref to set.

  */

 function setLocalizedPref(aPrefName, aValue) {

   const nsIPLS = Ci.nsIPrefLocalizedString;

   try {

     var pls = Components.classes["@mozilla.org/pref-localizedstring;1"]

                         .createInstance(Ci.nsIPrefLocalizedString);

     pls.data = aValue;

     Services.prefs.setComplexValue(aPrefName, nsIPLS, pls);

   } catch (ex) {}

 }

 /**

  * Wrapper for nsIPrefBranch::getBoolPref.

  * @param aPrefName

  *        The name of the pref to get.

  * @returns aDefault if the requested pref doesn't exist.

  */

 function getBoolPref(aName, aDefault) {

   try {

     return Services.prefs.getBoolPref(aName);

   } catch (ex) {

     return aDefault;

   }

 }

 /**

  * Get a unique nsIFile object with a sanitized name, based on the engine name.

  * @param aName

  *        A name to "sanitize". Can be an empty string, in which case a random

  *        8 character filename will be produced.

  * @returns A nsIFile object in the user's search engines directory with a

  *          unique sanitized name.

  */

 function getSanitizedFile(aName) {

   var fileName = sanitizeName(aName) + ".xml";

   var file = getDir(NS_APP_USER_SEARCH_DIR);

   file.append(fileName);

   file.createUnique(Ci.nsIFile.NORMAL_FILE_TYPE, PERMS_FILE);

   return file;

 }

 /**

  * @return a sanitized name to be used as a filename, or a random name

  *         if a sanitized name cannot be obtained (if aName contains

  *         no valid characters).

  */

 function sanitizeName(aName) {

   const maxLength = 60;

   const minLength = 1;

   var name = aName.toLowerCase();

   name = name.replace(/\s+/g, "-");

   name = name.replace(/[^-a-z0-9]/g, "");

   // Use a random name if our input had no valid characters.

   if (name.length < minLength)

     name = Math.random().toString(36).replace(/^.*\./, '');

   // Force max length.

   return name.substring(0, maxLength);

 }

 /**

  * Retrieve a pref from the search param branch.

  *

  * @param prefName

  *        The name of the pref.

  **/

 function getMozParamPref(prefName)

   Services.prefs.getCharPref(BROWSER_SEARCH_PREF + "param." + prefName);

 /**

  * Notifies watchers of SEARCH_ENGINE_TOPIC about changes to an engine or to

  * the state of the search service.

  *

  * @param aEngine

  *        The nsISearchEngine object to which the change applies.

  * @param aVerb

  *        A verb describing the change.

  *

  * @see nsIBrowserSearchService.idl

  */

 let gInitialized = false;

 function notifyAction(aEngine, aVerb) {

   if (gInitialized) {

     LOG("NOTIFY: Engine: \"" + aEngine.name + "\"; Verb: \"" + aVerb + "\"");

     Services.obs.notifyObservers(aEngine, SEARCH_ENGINE_TOPIC, aVerb);

   }

 }

 function  parseJsonFromStream(aInputStream) {

   const json = Cc["@mozilla.org/dom/json;1"].createInstance(Ci.nsIJSON);

   const data = json.decodeFromStream(aInputStream, aInputStream.available());

   return data;

 }

 /**

  * Simple object representing a name/value pair.

  */

 function QueryParameter(aName, aValue, aPurpose) {

   if (!aName || (aValue == null))

     FAIL("missing name or value for QueryParameter!");

   this.name = aName;

   this.value = aValue;

   this.purpose = aPurpose;

 }

 /**

  * Perform OpenSearch parameter substitution on aParamValue.

  *

  * @param aParamValue

  *        A string containing OpenSearch search parameters.

  * @param aSearchTerms

  *        The user-provided search terms. This string will inserted into

  *        aParamValue as the value of the OS_PARAM_USER_DEFINED parameter.

  *        This value must already be escaped appropriately - it is inserted

  *        as-is.

  * @param aEngine

  *        The engine which owns the string being acted on.

  *

  * @see http://opensearch.a9.com/spec/1.1/querysyntax/#core

  */

 function ParamSubstitution(aParamValue, aSearchTerms, aEngine) {

   var value = aParamValue;

   var distributionID = MOZ_DISTRIBUTION_ID;

   try {

     distributionID = Services.prefs.getCharPref(BROWSER_SEARCH_PREF + "distributionID");

   }

   catch (ex) { }

   var official = MOZ_OFFICIAL;

   try {

     if (Services.prefs.getBoolPref(BROWSER_SEARCH_PREF + "official"))

       official = "official";

     else

       official = "unofficial";

   }

   catch (ex) { }

   // Custom search parameters. These are only available to default search

   // engines.

   if (aEngine._isDefault) {

     value = value.replace(MOZ_PARAM_LOCALE, getLocale());

     value = value.replace(MOZ_PARAM_DIST_ID, distributionID);

     value = value.replace(MOZ_PARAM_OFFICIAL, official);

   }

   // Insert the OpenSearch parameters we're confident about

   value = value.replace(OS_PARAM_USER_DEFINED, aSearchTerms);

   value = value.replace(OS_PARAM_INPUT_ENCODING, aEngine.queryCharset);

   value = value.replace(OS_PARAM_LANGUAGE,

                         getLocale() || OS_PARAM_LANGUAGE_DEF);

   value = value.replace(OS_PARAM_OUTPUT_ENCODING,

                         OS_PARAM_OUTPUT_ENCODING_DEF);

   // Replace any optional parameters

   value = value.replace(OS_PARAM_OPTIONAL, "");

   // Insert any remaining required params with our default values

   for (var i = 0; i < OS_UNSUPPORTED_PARAMS.length; ++i) {

     value = value.replace(OS_UNSUPPORTED_PARAMS[i][0],

                           OS_UNSUPPORTED_PARAMS[i][1]);

   }

   return value;

 }

 /**

  * Creates an engineURL object, which holds the query URL and all parameters.

  *

  * @param aType

  *        A string containing the name of the MIME type of the search results

  *        returned by this URL.

  * @param aMethod

  *        The HTTP request method. Must be a case insensitive value of either

  *        "GET" or "POST".

  * @param aTemplate

  *        The URL to which search queries should be sent. For GET requests,

  *        must contain the string "{searchTerms}", to indicate where the user

  *        entered search terms should be inserted.

  * @param aResultDomain

  *        The root domain for this URL.  Defaults to the template's host.

  *

  * @see http://opensearch.a9.com/spec/1.1/querysyntax/#urltag

  *

  * @throws NS_ERROR_NOT_IMPLEMENTED if aType is unsupported.

  */

 function EngineURL(aType, aMethod, aTemplate, aResultDomain) {

   if (!aType || !aMethod || !aTemplate)

     FAIL("missing type, method or template for EngineURL!");

   var method = aMethod.toUpperCase();

   var type   = aType.toLowerCase();

   if (method != "GET" && method != "POST")

     FAIL("method passed to EngineURL must be \"GET\" or \"POST\"");

   this.type     = type;

   this.method   = method;

   this.params   = [];

   this.rels     = [];

   // Don't serialize expanded mozparams

   this.mozparams = {};

   var templateURI = makeURI(aTemplate);

   if (!templateURI)

     FAIL("new EngineURL: template is not a valid URI!", Cr.NS_ERROR_FAILURE);

   switch (templateURI.scheme) {

     case "http":

     case "https":

     // Disable these for now, see bug 295018

     // case "file":

     // case "resource":

       this.template = aTemplate;

       break;

     default:

       FAIL("new EngineURL: template uses invalid scheme!", Cr.NS_ERROR_FAILURE);

   }

   // If no resultDomain was specified in the engine definition file, use the

   // host from the template.

   this.resultDomain = aResultDomain || templateURI.host;

   // We never want to return a "www." prefix, so eventually strip it.

   if (this.resultDomain.startsWith("www.")) {

     this.resultDomain = this.resultDomain.substr(4);

   }

 }

 EngineURL.prototype = {

   addParam: function SRCH_EURL_addParam(aName, aValue, aPurpose) {

     this.params.push(new QueryParameter(aName, aValue, aPurpose));

   },

   // Note: This method requires that aObj has a unique name or the previous MozParams entry with

   // that name will be overwritten.

   _addMozParam: function SRCH_EURL__addMozParam(aObj) {

     aObj.mozparam = true;

     this.mozparams[aObj.name] = aObj;

   },

   reevalMozParams: function(engine) {

     for (let param of this.params) {

       let mozparam = this.mozparams[param.name];

       if (mozparam && mozparam.positionDependent) {

         // the condition is a string in the form of "topN", extract N as int

         let positionStr = mozparam.condition.slice("top".length);

         let position = parseInt(positionStr, 10);

         let engines;

         try {

           // This will throw if we're not initialized yet (which shouldn't happen), just 

           // ignore and move on with the false Value (checking isInitialized also throws)

           // XXX

           engines = Services.search.getVisibleEngines({});

         } catch (ex) {

           LOG("reevalMozParams called before search service initialization!?");

           break;

         }

         let index = engines.map((e) => e.wrappedJSObject).indexOf(engine.wrappedJSObject);

         let isTopN = index > -1 && (index + 1) <= position;

         param.value = isTopN ? mozparam.trueValue : mozparam.falseValue;

       }

     }

   },

   getSubmission: function SRCH_EURL_getSubmission(aSearchTerms, aEngine, aPurpose) {

     this.reevalMozParams(aEngine);

     var url = ParamSubstitution(this.template, aSearchTerms, aEngine);

     // Default to an empty string if the purpose is not provided so that default purpose params

     // (purpose="") work consistently rather than having to define "null" and "" purposes.

     var purpose = aPurpose || "";

     // Create an application/x-www-form-urlencoded representation of our params

     // (name=value&name=value&name=value)

     var dataString = "";

     for (var i = 0; i < this.params.length; ++i) {

       var param = this.params[i];

       // If this parameter has a purpose, only add it if the purpose matches

       if (param.purpose !== undefined && param.purpose != purpose)

         continue;

       var value = ParamSubstitution(param.value, aSearchTerms, aEngine);

       dataString += (i > 0 ? "&" : "") + param.name + "=" + value;

     }

     var postData = null;

     if (this.method == "GET") {

       // GET method requests have no post data, and append the encoded

       // query string to the url...

       if (url.indexOf("?") == -1 && dataString)

         url += "?";

       url += dataString;

     } else if (this.method == "POST") {

       // POST method requests must wrap the encoded text in a MIME

       // stream and supply that as POSTDATA.

       var stringStream = Cc["@mozilla.org/io/string-input-stream;1"].

                          createInstance(Ci.nsIStringInputStream);

       stringStream.data = dataString;

       postData = Cc["@mozilla.org/network/mime-input-stream;1"].

                  createInstance(Ci.nsIMIMEInputStream);

       postData.addHeader("Content-Type", "application/x-www-form-urlencoded");

       postData.addContentLength = true;

       postData.setData(stringStream);

     }

     return new Submission(makeURI(url), postData);

   },

   _hasRelation: function SRC_EURL__hasRelation(aRel)

     this.rels.some(function(e) e == aRel.toLowerCase()),

   _initWithJSON: function SRC_EURL__initWithJSON(aJson, aEngine) {

     if (!aJson.params)

       return;

     this.rels = aJson.rels;

     for (let i = 0; i < aJson.params.length; ++i) {

       let param = aJson.params[i];

       if (param.mozparam) {

         if (param.condition == "defaultEngine") {

           if (aEngine._isDefaultEngine())

             this.addParam(param.name, param.trueValue);

           else

             this.addParam(param.name, param.falseValue);

         } else if (param.condition == "pref") {

           let value = getMozParamPref(param.pref);

           this.addParam(param.name, value);

         }

         this._addMozParam(param);

       }

       else

         this.addParam(param.name, param.value, param.purpose);

     }

   },

   /**

    * Creates a JavaScript object that represents this URL.

    * @returns An object suitable for serialization as JSON.

    **/

   _serializeToJSON: function SRCH_EURL__serializeToJSON() {

     var json = {

       template: this.template,

       rels: this.rels,

       resultDomain: this.resultDomain

     };

     if (this.type != URLTYPE_SEARCH_HTML)

       json.type = this.type;

     if (this.method != "GET")

       json.method = this.method;

     function collapseMozParams(aParam)

       this.mozparams[aParam.name] || aParam;

     json.params = this.params.map(collapseMozParams, this);

     return json;

   },

   /**

    * Serializes the engine object to a OpenSearch Url element.

    * @param aDoc

    *        The document to use to create the Url element.

    * @param aElement

    *        The element to which the created Url element is appended.

    *

    * @see http://opensearch.a9.com/spec/1.1/querysyntax/#urltag

    */

   _serializeToElement: function SRCH_EURL_serializeToEl(aDoc, aElement) {

     var url = aDoc.createElementNS(OPENSEARCH_NS_11, "Url");

     url.setAttribute("type", this.type);

     url.setAttribute("method", this.method);

     url.setAttribute("template", this.template);

     if (this.rels.length)

       url.setAttribute("rel", this.rels.join(" "));

     if (this.resultDomain)

       url.setAttribute("resultDomain", this.resultDomain);

     for (var i = 0; i < this.params.length; ++i) {

       var param = aDoc.createElementNS(OPENSEARCH_NS_11, "Param");

       param.setAttribute("name", this.params[i].name);

       param.setAttribute("value", this.params[i].value);

       url.appendChild(aDoc.createTextNode("\n  "));

       url.appendChild(param);

     }

     url.appendChild(aDoc.createTextNode("\n"));

     aElement.appendChild(url);

   }

 };

 /**

  * nsISearchEngine constructor.

  * @param aLocation

  *        A nsILocalFile or nsIURI object representing the location of the

  *        search engine data file.

  * @param aSourceDataType

  *        The data type of the file used to describe the engine. Must be either

  *        DATA_XML or DATA_TEXT.

  * @param aIsReadOnly

  *        Boolean indicating whether the engine should be treated as read-only.

  *        Read only engines cannot be serialized to file.

  */

 function Engine(aLocation, aSourceDataType, aIsReadOnly) {

   this._dataType = aSourceDataType;

   this._readOnly = aIsReadOnly;

   this._urls = [];

   if (aLocation.type) {

     if (aLocation.type == "filePath")

       this._file = aLocation.value;

     else if (aLocation.type == "uri")

       this._uri = aLocation.value;

   } else if (aLocation instanceof Ci.nsILocalFile) {

     // we already have a file (e.g. loading engines from disk)

     this._file = aLocation;

   } else if (aLocation instanceof Ci.nsIURI) {

     switch (aLocation.scheme) {

       case "https":

       case "http":

       case "ftp":

       case "data":

       case "file":

       case "resource":

       case "chrome":

         this._uri = aLocation;

         break;

       default:

         ERROR("Invalid URI passed to the nsISearchEngine constructor",

               Cr.NS_ERROR_INVALID_ARG);

     }

   } else

     ERROR("Engine location is neither a File nor a URI object",

           Cr.NS_ERROR_INVALID_ARG);

 }

 Engine.prototype = {

   // The engine's alias (can be null). Initialized to |undefined| to indicate

   // not-initialized-from-engineMetadataService.

   _alias: undefined,

   // A distribution-unique identifier for the engine. Either null or set

   // when loaded. See getter.

   _identifier: undefined,

   // The data describing the engine. Is either an array of bytes, for Sherlock

   // files, or an XML document element, for XML plugins.

   _data: null,

   // The engine's data type. See data types (DATA_) defined above.

   _dataType: null,

   // Whether or not the engine is readonly.

   _readOnly: true,

   // The engine's description

   _description: "",

   // Used to store the engine to replace, if we're an update to an existing

   // engine.

   _engineToUpdate: null,

   // The file from which the plugin was loaded.

   __file: null,

   get _file() {

     if (this.__file && !(this.__file instanceof Ci.nsILocalFile)) {

       let file = Cc["@mozilla.org/file/local;1"].createInstance(Ci.nsILocalFile);

       file.persistentDescriptor = this.__file;

       return this.__file = file;

     }

     return this.__file;

   },

   set _file(aValue) {

     this.__file = aValue;

   },

   // Set to true if the engine has a preferred icon (an icon that should not be

   // overridden by a non-preferred icon).

   _hasPreferredIcon: null,

   // Whether the engine is hidden from the user.

   _hidden: null,

   // The engine's name.

   _name: null,

   // The engine type. See engine types (TYPE_) defined above.

   _type: null,

   // The name of the charset used to submit the search terms.

   _queryCharset: null,

   // The engine's raw SearchForm value (URL string pointing to a search form).

   __searchForm: null,

   get _searchForm() {

     return this.__searchForm;

   },

   set _searchForm(aValue) {

     if (/^https?:/i.test(aValue))

       this.__searchForm = aValue;

     else

       LOG("_searchForm: Invalid URL dropped for " + this._name ||

           "the current engine");

   },

   // The URI object from which the engine was retrieved.

   // This is null for engines loaded from disk, but present for engines loaded

   // from chrome:// URIs.

   __uri: null,

   get _uri() {

     if (this.__uri && !(this.__uri instanceof Ci.nsIURI))

       this.__uri = makeURI(this.__uri);

     return this.__uri;

   },

   set _uri(aValue) {

     this.__uri = aValue;

   },

   // Whether to obtain user confirmation before adding the engine. This is only

   // used when the engine is first added to the list.

   _confirm: false,

   // Whether to set this as the current engine as soon as it is loaded.  This

   // is only used when the engine is first added to the list.

   _useNow: false,

   // A function to be invoked when this engine object's addition completes (or

   // fails). Only used for installation via addEngine.

   _installCallback: null,

   // Where the engine was loaded from. Can be one of: SEARCH_APP_DIR,

   // SEARCH_PROFILE_DIR, SEARCH_IN_EXTENSION.

   __installLocation: null,

   // The number of days between update checks for new versions

   _updateInterval: null,

   // The url to check at for a new update

   _updateURL: null,

   // The url to check for a new icon

   _iconUpdateURL: null,

   /* Deferred serialization task. */

   _lazySerializeTask: null,

   /**

    * Retrieves the data from the engine's file. If the engine's dataType is

    * XML, the document element is placed in the engine's data field. For text

    * engines, the data is just read directly from file and placed as an array

    * of lines in the engine's data field.

    */

   _initFromFile: function SRCH_ENG_initFromFile() {

     if (!this._file || !this._file.exists())

       FAIL("File must exist before calling initFromFile!", Cr.NS_ERROR_UNEXPECTED);

     var fileInStream = Cc["@mozilla.org/network/file-input-stream;1"].

                        createInstance(Ci.nsIFileInputStream);

     fileInStream.init(this._file, MODE_RDONLY, PERMS_FILE, false);

     if (this._dataType == SEARCH_DATA_XML) {

       var domParser = Cc["@mozilla.org/xmlextras/domparser;1"].

                       createInstance(Ci.nsIDOMParser);

       var doc = domParser.parseFromStream(fileInStream, "UTF-8",

                                           this._file.fileSize,

                                           "text/xml");

       this._data = doc.documentElement;

     } else {

       ERROR("Unsuppored engine _dataType in _initFromFile: \"" +

             this._dataType + "\"",

             Cr.NS_ERROR_UNEXPECTED);

     }

     fileInStream.close();

     // Now that the data is loaded, initialize the engine object

     this._initFromData();

   },

   /**

    * Retrieves the data from the engine's file asynchronously. If the engine's

    * dataType is XML, the document element is placed in the engine's data field.

    *

    * @returns {Promise} A promise, resolved successfully if initializing from

    * data succeeds, rejected if it fails.

    */

   _asyncInitFromFile: function SRCH_ENG__asyncInitFromFile() {

     return TaskUtils.spawn(function() {

       if (!this._file || !(yield OS.File.exists(this._file.path)))

         FAIL("File must exist before calling initFromFile!", Cr.NS_ERROR_UNEXPECTED);

       if (this._dataType == SEARCH_DATA_XML) {

         let fileURI = NetUtil.ioService.newFileURI(this._file);

         yield this._retrieveSearchXMLData(fileURI.spec);

       } else {

         ERROR("Unsuppored engine _dataType in _initFromFile: \"" +

               this._dataType + "\"",

               Cr.NS_ERROR_UNEXPECTED);

       }

       // Now that the data is loaded, initialize the engine object

       this._initFromData();

     }.bind(this));

   },

   /**

    * Retrieves the engine data from a URI. Initializes the engine, flushes to

    * disk, and notifies the search service once initialization is complete.

    */

   _initFromURIAndLoad: function SRCH_ENG_initFromURIAndLoad() {

     ENSURE_WARN(this._uri instanceof Ci.nsIURI,

                 "Must have URI when calling _initFromURIAndLoad!",

                 Cr.NS_ERROR_UNEXPECTED);

     LOG("_initFromURIAndLoad: Downloading engine from: \"" + this._uri.spec + "\".");

     var chan = NetUtil.ioService.newChannelFromURI(this._uri);

     if (this._engineToUpdate && (chan instanceof Ci.nsIHttpChannel)) {

       var lastModified = engineMetadataService.getAttr(this._engineToUpdate,

                                                        "updatelastmodified");

       if (lastModified)

         chan.setRequestHeader("If-Modified-Since", lastModified, false);

     }

     var listener = new loadListener(chan, this, this._onLoad);

     chan.notificationCallbacks = listener;

     chan.asyncOpen(listener, null);

   },

   /**

    * Retrieves the engine data from a URI asynchronously and initializes it.

    *

    * @returns {Promise} A promise, resolved successfully if retrieveing data

    * succeeds.

    */

   _asyncInitFromURI: function SRCH_ENG__asyncInitFromURI() {

     return TaskUtils.spawn(function() {

       LOG("_asyncInitFromURI: Loading engine from: \"" + this._uri.spec + "\".");

       yield this._retrieveSearchXMLData(this._uri.spec);

       // Now that the data is loaded, initialize the engine object

       this._initFromData();

     }.bind(this));

   },

   /**

    * Retrieves the engine data for a given URI asynchronously.

    *

    * @returns {Promise} A promise, resolved successfully if retrieveing data

    * succeeds.

    */

   _retrieveSearchXMLData: function SRCH_ENG__retrieveSearchXMLData(aURL) {

     let deferred = Promise.defer();

     let request = Cc["@mozilla.org/xmlextras/xmlhttprequest;1"].

                     createInstance(Ci.nsIXMLHttpRequest);

     request.overrideMimeType("text/xml");

     request.onload = (aEvent) => {

       let responseXML = aEvent.target.responseXML;

       this._data = responseXML.documentElement;

       deferred.resolve();

     };

     request.onerror = function(aEvent) {

       deferred.resolve();

     };

     request.open("GET", aURL, true);

     request.send();

     return deferred.promise;

   },

   _initFromURISync: function SRCH_ENG_initFromURISync() {

     ENSURE_WARN(this._uri instanceof Ci.nsIURI,

                 "Must have URI when calling _initFromURISync!",

                 Cr.NS_ERROR_UNEXPECTED);

     ENSURE_WARN(this._uri.schemeIs("chrome"), "_initFromURISync called for non-chrome URI",

                 Cr.NS_ERROR_FAILURE);

     LOG("_initFromURISync: Loading engine from: \"" + this._uri.spec + "\".");

     var chan = NetUtil.ioService.newChannelFromURI(this._uri);

     var stream = chan.open();

     var parser = Cc["@mozilla.org/xmlextras/domparser;1"].

                  createInstance(Ci.nsIDOMParser);

     var doc = parser.parseFromStream(stream, "UTF-8", stream.available(), "text/xml");

     this._data = doc.documentElement;

     // Now that the data is loaded, initialize the engine object

     this._initFromData();

   },

   /**

    * Attempts to find an EngineURL object in the set of EngineURLs for

    * this Engine that has the given type string.  (This corresponds to the

    * "type" attribute in the "Url" node in the OpenSearch spec.)

    * This method will return the first matching URL object found, or null

    * if no matching URL is found.

    *

    * @param aType string to match the EngineURL's type attribute

    * @param aRel [optional] only return URLs that with this rel value

    */

   _getURLOfType: function SRCH_ENG__getURLOfType(aType, aRel) {

     for (var i = 0; i < this._urls.length; ++i) {

       if (this._urls[i].type == aType && (!aRel || this._urls[i]._hasRelation(aRel)))

         return this._urls[i];

     }

     return null;

   },

   _confirmAddEngine: function SRCH_SVC_confirmAddEngine() {

     var stringBundle = Services.strings.createBundle(SEARCH_BUNDLE);

     var titleMessage = stringBundle.GetStringFromName("addEngineConfirmTitle");

     // Display only the hostname portion of the URL.

     var dialogMessage =

         stringBundle.formatStringFromName("addEngineConfirmation",

                                           [this._name, this._uri.host], 2);

     var checkboxMessage = null;

     if (!getBoolPref(BROWSER_SEARCH_PREF + "noCurrentEngine", false))

       checkboxMessage = stringBundle.GetStringFromName("addEngineAsCurrentText");

     var addButtonLabel =

         stringBundle.GetStringFromName("addEngineAddButtonLabel");

     var ps = Services.prompt;

     var buttonFlags = (ps.BUTTON_TITLE_IS_STRING * ps.BUTTON_POS_0) +

                       (ps.BUTTON_TITLE_CANCEL    * ps.BUTTON_POS_1) +

                        ps.BUTTON_POS_0_DEFAULT;

     var checked = {value: false};

     // confirmEx returns the index of the button that was pressed.  Since "Add"

     // is button 0, we want to return the negation of that value.

     var confirm = !ps.confirmEx(null,

                                 titleMessage,

                                 dialogMessage,

                                 buttonFlags,

                                 addButtonLabel,

                                 null, null, // button 1 & 2 names not used

                                 checkboxMessage,

                                 checked);

     return {confirmed: confirm, useNow: checked.value};

   },

   /**

    * Handle the successful download of an engine. Initializes the engine and

    * triggers parsing of the data. The engine is then flushed to disk. Notifies

    * the search service once initialization is complete.

    */

   _onLoad: function SRCH_ENG_onLoad(aBytes, aEngine) {

     /**

      * Handle an error during the load of an engine by notifying the engine's

      * error callback, if any.

      */

     function onError(errorCode = Ci.nsISearchInstallCallback.ERROR_UNKNOWN_FAILURE) {

       // Notify the callback of the failure

       if (aEngine._installCallback) {

         aEngine._installCallback(errorCode);

       }

     }

     function promptError(strings = {}, error = undefined) {

       onError(error);

       if (aEngine._engineToUpdate) {

         // We're in an update, so just fail quietly

         LOG("updating " + aEngine._engineToUpdate.name + " failed");

         return;

       }

       var brandBundle = Services.strings.createBundle(BRAND_BUNDLE);

       var brandName = brandBundle.GetStringFromName("brandShortName");

       var searchBundle = Services.strings.createBundle(SEARCH_BUNDLE);

       var msgStringName = strings.error || "error_loading_engine_msg2";

       var titleStringName = strings.title || "error_loading_engine_title";

       var title = searchBundle.GetStringFromName(titleStringName);

       var text = searchBundle.formatStringFromName(msgStringName,

                                                    [brandName, aEngine._location],

                                                    2);

       Services.ww.getNewPrompter(null).alert(title, text);

     }

     if (!aBytes) {

       promptError();

       return;

     }

     var engineToUpdate = null;

     if (aEngine._engineToUpdate) {

       engineToUpdate = aEngine._engineToUpdate.wrappedJSObject;

       // Make this new engine use the old engine's file.

       aEngine._file = engineToUpdate._file;

     }

     switch (aEngine._dataType) {

       case SEARCH_DATA_XML:

         var parser = Cc["@mozilla.org/xmlextras/domparser;1"].

                      createInstance(Ci.nsIDOMParser);

         var doc = parser.parseFromBuffer(aBytes, aBytes.length, "text/xml");

         aEngine._data = doc.documentElement;

         break;

       case SEARCH_DATA_TEXT:

         aEngine._data = aBytes;

         break;

       default:

         promptError();

         LOG("_onLoad: Bogus engine _dataType: \"" + this._dataType + "\"");

         return;

     }

     try {

       // Initialize the engine from the obtained data

       aEngine._initFromData();

     } catch (ex) {

       LOG("_onLoad: Failed to init engine!\n" + ex);

       // Report an error to the user

       promptError();

       return;

     }

     // Check that when adding a new engine (e.g., not updating an

     // existing one), a duplicate engine does not already exist.

     if (!engineToUpdate) {

       if (Services.search.getEngineByName(aEngine.name)) {

         // If we're confirming the engine load, then display a "this is a

         // duplicate engine" prompt; otherwise, fail silently.

         if (aEngine._confirm) {

           promptError({ error: "error_duplicate_engine_msg",

                         title: "error_invalid_engine_title"

                       }, Ci.nsISearchInstallCallback.ERROR_DUPLICATE_ENGINE);

         } else {

           onError(Ci.nsISearchInstallCallback.ERROR_DUPLICATE_ENGINE);

         }

         LOG("_onLoad: duplicate engine found, bailing");

         return;

       }

     }

     // If requested, confirm the addition now that we have the title.

     // This property is only ever true for engines added via

     // nsIBrowserSearchService::addEngine.

     if (aEngine._confirm) {

       var confirmation = aEngine._confirmAddEngine();

       LOG("_onLoad: confirm is " + confirmation.confirmed +

           "; useNow is " + confirmation.useNow);

       if (!confirmation.confirmed) {

         onError();

         return;

       }

       aEngine._useNow = confirmation.useNow;

     }

     // If we don't yet have a file, get one now. The only case where we would

     // already have a file is if this is an update and _file was set above.

     if (!aEngine._file)

       aEngine._file = getSanitizedFile(aEngine.name);

     if (engineToUpdate) {

       // Keep track of the last modified date, so that we can make conditional

       // requests for future updates.

       engineMetadataService.setAttr(aEngine, "updatelastmodified",

                                     (new Date()).toUTCString());

       // If we're updating an app-shipped engine, ensure that the updateURLs

       // are the same.

       if (engineToUpdate._isInAppDir) {

         let oldUpdateURL = engineToUpdate._updateURL;

         let newUpdateURL = aEngine._updateURL;

         let oldSelfURL = engineToUpdate._getURLOfType(URLTYPE_OPENSEARCH, "self");

         if (oldSelfURL) {

           oldUpdateURL = oldSelfURL.template;

           let newSelfURL = aEngine._getURLOfType(URLTYPE_OPENSEARCH, "self");

           if (!newSelfURL) {

             LOG("_onLoad: updateURL missing in updated engine for " +

                 aEngine.name + " aborted");

             onError();

             return;

           }

           newUpdateURL = newSelfURL.template;

         }

         if (oldUpdateURL != newUpdateURL) {

           LOG("_onLoad: updateURLs do not match! Update of " + aEngine.name + " aborted");

           onError();

           return;

         }

       }

       // Set the new engine's icon, if it doesn't yet have one.

       if (!aEngine._iconURI && engineToUpdate._iconURI)

         aEngine._iconURI = engineToUpdate._iconURI;

     }

     // Write the engine to file. For readOnly engines, they'll be stored in the

     // cache following the notification below.

     if (!aEngine._readOnly)

       aEngine._serializeToFile();

     // Notify the search service of the successful load. It will deal with

     // updates by checking aEngine._engineToUpdate.

     notifyAction(aEngine, SEARCH_ENGINE_LOADED);

     // Notify the callback if needed

     if (aEngine._installCallback) {

       aEngine._installCallback();

     }

   },

   /**

    * Creates a key by serializing an object that contains the icon's width

    * and height.

    *

    * @param aWidth

    *        Width of the icon.

    * @param aHeight

    *        Height of the icon.

    * @returns key string

    */

   _getIconKey: function SRCH_ENG_getIconKey(aWidth, aHeight) {

     let keyObj = {

      width: aWidth,

      height: aHeight

     };

     return JSON.stringify(keyObj);

   },

   /**

    * Add an icon to the icon map used by getIconURIBySize() and getIcons().

    *

    * @param aWidth

    *        Width of the icon.

    * @param aHeight

    *        Height of the icon.

    * @param aURISpec

    *        String with the icon's URI.

    */

   _addIconToMap: function SRCH_ENG_addIconToMap(aWidth, aHeight, aURISpec) {

     // Use an object instead of a Map() because it needs to be serializable.

     this._iconMapObj = this._iconMapObj || {};

     let key = this._getIconKey(aWidth, aHeight);

     this._iconMapObj[key] = aURISpec;

   },

   /**

    * Sets the .iconURI property of the engine. If both aWidth and aHeight are

    * provided an entry will be added to _iconMapObj that will enable accessing

    * icon's data through getIcons() and getIconURIBySize() APIs.

    *

    *  @param aIconURL

    *         A URI string pointing to the engine's icon. Must have a http[s],

    *         ftp, or data scheme. Icons with HTTP[S] or FTP schemes will be

    *         downloaded and converted to data URIs for storage in the engine

    *         XML files, if the engine is not readonly.

    *  @param aIsPreferred

    *         Whether or not this icon is to be preferred. Preferred icons can

    *         override non-preferred icons.

    *  @param aWidth (optional)

    *         Width of the icon.

    *  @param aHeight (optional)

    *         Height of the icon.

    */

   _setIcon: function SRCH_ENG_setIcon(aIconURL, aIsPreferred, aWidth, aHeight) {

     var uri = makeURI(aIconURL);

     // Ignore bad URIs

     if (!uri)

       return;

     LOG("_setIcon: Setting icon url \"" + limitURILength(uri.spec) + "\" for engine \""

         + this.name + "\".");

     // Only accept remote icons from http[s] or ftp

     switch (uri.scheme) {

       case "data":

         if (!this._hasPreferredIcon || aIsPreferred) {

           this._iconURI = uri;

           notifyAction(this, SEARCH_ENGINE_CHANGED);

           this._hasPreferredIcon = aIsPreferred;

         }

         if (aWidth && aHeight) {

           this._addIconToMap(aWidth, aHeight, aIconURL)

         }

         break;

       case "http":

       case "https":

       case "ftp":

         // No use downloading the icon if the engine file is read-only

         if (!this._readOnly ||

             getBoolPref(BROWSER_SEARCH_PREF + "cache.enabled", true)) {

           LOG("_setIcon: Downloading icon: \"" + uri.spec +

               "\" for engine: \"" + this.name + "\"");

           var chan = NetUtil.ioService.newChannelFromURI(uri);

           function iconLoadCallback(aByteArray, aEngine) {

             // This callback may run after we've already set a preferred icon,

             // so check again.

             if (aEngine._hasPreferredIcon && !aIsPreferred)

               return;

             if (!aByteArray || aByteArray.length > MAX_ICON_SIZE) {

               LOG("iconLoadCallback: load failed, or the icon was too large!");

               return;

             }

             var str = btoa(String.fromCharCode.apply(null, aByteArray));

             let dataURL = ICON_DATAURL_PREFIX + str;

             aEngine._iconURI = makeURI(dataURL);

             if (aWidth && aHeight) {

               aEngine._addIconToMap(aWidth, aHeight, dataURL)

             }

             // The engine might not have a file yet, if it's being downloaded,

             // because the request for the engine file itself (_onLoad) may not

             // yet be complete. In that case, this change will be written to

             // file when _onLoad is called. For readonly engines, we'll store

             // the changes in the cache once notified below.

             if (aEngine._file && !aEngine._readOnly)

               aEngine._serializeToFile();

             notifyAction(aEngine, SEARCH_ENGINE_CHANGED);

             aEngine._hasPreferredIcon = aIsPreferred;

           }

           // If we're currently acting as an "update engine", then the callback

           // should set the icon on the engine we're updating and not us, since

           // |this| might be gone by the time the callback runs.

           var engineToSet = this._engineToUpdate || this;

           var listener = new loadListener(chan, engineToSet, iconLoadCallback);

           chan.notificationCallbacks = listener;

           chan.asyncOpen(listener, null);

         }

         break;

     }

   },

   /**

    * Initialize this Engine object from the collected data.

    */

   _initFromData: function SRCH_ENG_initFromData() {

     ENSURE_WARN(this._data, "Can't init an engine with no data!",

                 Cr.NS_ERROR_UNEXPECTED);

     // Find out what type of engine we are

     switch (this._dataType) {

       case SEARCH_DATA_XML:

         if (checkNameSpace(this._data, [MOZSEARCH_LOCALNAME],

             [MOZSEARCH_NS_10])) {

           LOG("_init: Initing MozSearch plugin from " + this._location);

           this._type = SEARCH_TYPE_MOZSEARCH;

           this._parseAsMozSearch();

         } else if (checkNameSpace(this._data, [OPENSEARCH_LOCALNAME],

                                   OPENSEARCH_NAMESPACES)) {

           LOG("_init: Initing OpenSearch plugin from " + this._location);

           this._type = SEARCH_TYPE_OPENSEARCH;

           this._parseAsOpenSearch();

         } else

           FAIL(this._location + " is not a valid search plugin.", Cr.NS_ERROR_FAILURE);

         break;

       case SEARCH_DATA_TEXT:

         LOG("_init: Initing Sherlock plugin from " + this._location);

         // the only text-based format we support is Sherlock

         this._type = SEARCH_TYPE_SHERLOCK;

         this._parseAsSherlock();

     }

     // No need to keep a ref to our data (which in some cases can be a document

     // element) past this point

     this._data = null;

   },

   /**

    * Initialize this Engine object from a collection of metadata.

    */

   _initFromMetadata: function SRCH_ENG_initMetaData(aName, aIconURL, aAlias,

                                                     aDescription, aMethod,

                                                     aTemplate) {

     ENSURE_WARN(!this._readOnly,

                 "Can't call _initFromMetaData on a readonly engine!",

                 Cr.NS_ERROR_FAILURE);

     this._urls.push(new EngineURL(URLTYPE_SEARCH_HTML, aMethod, aTemplate));

     this._name = aName;

     this.alias = aAlias;

     this._description = aDescription;

     this._setIcon(aIconURL, true);

     this._serializeToFile();

   },

   /**

    * Extracts data from an OpenSearch URL element and creates an EngineURL

    * object which is then added to the engine's list of URLs.

    *

    * @throws NS_ERROR_FAILURE if a URL object could not be created.

    *

    * @see http://opensearch.a9.com/spec/1.1/querysyntax/#urltag.

    * @see EngineURL()

    */

   _parseURL: function SRCH_ENG_parseURL(aElement) {

     var type     = aElement.getAttribute("type");

     // According to the spec, method is optional, defaulting to "GET" if not

     // specified

     var method   = aElement.getAttribute("method") || "GET";

     var template = aElement.getAttribute("template");

     var resultDomain = aElement.getAttribute("resultdomain");

     try {

       var url = new EngineURL(type, method, template, resultDomain);

     } catch (ex) {

       FAIL("_parseURL: failed to add " + template + " as a URL",

            Cr.NS_ERROR_FAILURE);

     }

     if (aElement.hasAttribute("rel"))

       url.rels = aElement.getAttribute("rel").toLowerCase().split(/\s+/);

     for (var i = 0; i < aElement.childNodes.length; ++i) {

       var param = aElement.childNodes[i];

       if (param.localName == "Param") {

         try {

           url.addParam(param.getAttribute("name"), param.getAttribute("value"));

         } catch (ex) {

           // Ignore failure

           LOG("_parseURL: Url element has an invalid param");

         }

       } else if (param.localName == "MozParam" &&

                  // We only support MozParams for default search engines

                  this._isDefault) {

         var value;

         let condition = param.getAttribute("condition");

         // MozParams must have a condition to be valid

         if (!condition) {

           let engineLoc = this._location;

           let paramName = param.getAttribute("name");

           LOG("_parseURL: MozParam (" + paramName + ") without a condition attribute found parsing engine: " + engineLoc);

           continue;

         }

         switch (condition) {

           case "purpose":

             url.addParam(param.getAttribute("name"),

                          param.getAttribute("value"),

                          param.getAttribute("purpose"));

             // _addMozParam is not needed here since it can be serialized fine without. _addMozParam

             // also requires a unique "name" which is not normally the case when @purpose is used.

             break;

           case "defaultEngine":

             // If this engine was the default search engine, use the true value

             if (this._isDefaultEngine())

               value = param.getAttribute("trueValue");

             else

               value = param.getAttribute("falseValue");

             url.addParam(param.getAttribute("name"), value);

             url._addMozParam({"name": param.getAttribute("name"),

                               "falseValue": param.getAttribute("falseValue"),

                               "trueValue": param.getAttribute("trueValue"),

                               "condition": "defaultEngine"});

             break;

           case "pref":

             try {

               value = getMozParamPref(param.getAttribute("pref"), value);

               url.addParam(param.getAttribute("name"), value);

               url._addMozParam({"pref": param.getAttribute("pref"),

                                 "name": param.getAttribute("name"),

                                 "condition": "pref"});

             } catch (e) { }

             break;

           default:

             if (condition && condition.startsWith("top")) {

               url.addParam(param.getAttribute("name"), param.getAttribute("falseValue"));

               let mozparam = {"name": param.getAttribute("name"),

                               "falseValue": param.getAttribute("falseValue"),

                               "trueValue": param.getAttribute("trueValue"),

                               "condition": condition,

                               "positionDependent": true};

               url._addMozParam(mozparam);

             }

           break;

         }

       }

     }

     this._urls.push(url);

   },

   _isDefaultEngine: function SRCH_ENG__isDefaultEngine() {

     let defaultPrefB = Services.prefs.getDefaultBranch(BROWSER_SEARCH_PREF);

     let nsIPLS = Ci.nsIPrefLocalizedString;

     let defaultEngine;

     try {

       defaultEngine = defaultPrefB.getComplexValue("defaultenginename", nsIPLS).data;

     } catch (ex) {}

     return this.name == defaultEngine;

   },

   /**

    * Get the icon from an OpenSearch Image element.

    * @see http://opensearch.a9.com/spec/1.1/description/#image

    */

   _parseImage: function SRCH_ENG_parseImage(aElement) {

     LOG("_parseImage: Image textContent: \"" + limitURILength(aElement.textContent) + "\"");

     let width = parseInt(aElement.getAttribute("width"), 10);

     let height = parseInt(aElement.getAttribute("height"), 10);

     let isPrefered = width == 16 && height == 16;

     if (isNaN(width) || isNaN(height) || width <= 0 || height <=0) {

       LOG("OpenSearch image element must have positive width and height.");

       return;

     }

     this._setIcon(aElement.textContent, isPrefered, width, height);

   },

   _parseAsMozSearch: function SRCH_ENG_parseAsMoz() {

     //forward to the OpenSearch parser

     this._parseAsOpenSearch();

   },

   /**

    * Extract search engine information from the collected data to initialize

    * the engine object.

    */

   _parseAsOpenSearch: function SRCH_ENG_parseAsOS() {

     var doc = this._data;

     // The OpenSearch spec sets a default value for the input encoding.

     this._queryCharset = OS_PARAM_INPUT_ENCODING_DEF;

     for (var i = 0; i < doc.childNodes.length; ++i) {

       var child = doc.childNodes[i];

       switch (child.localName) {

         case "ShortName":

           this._name = child.textContent;

           break;

         case "Description":

           this._description = child.textContent;

           break;

         case "Url":

           try {

             this._parseURL(child);

           } catch (ex) {

             // Parsing of the element failed, just skip it.

             LOG("_parseAsOpenSearch: failed to parse URL child: " + ex);

           }

           break;

         case "Image":

           this._parseImage(child);

           break;

         case "InputEncoding":

           this._queryCharset = child.textContent.toUpperCase();

           break;

         // Non-OpenSearch elements

         case "SearchForm":

           this._searchForm = child.textContent;

           break;

         case "UpdateUrl":

           this._updateURL = child.textContent;

           break;

         case "UpdateInterval":

           this._updateInterval = parseInt(child.textContent);

           break;

         case "IconUpdateUrl":

           this._iconUpdateURL = child.textContent;

           break;

       }

     }

     if (!this.name || (this._urls.length == 0))

       FAIL("_parseAsOpenSearch: No name, or missing URL!", Cr.NS_ERROR_FAILURE);

     if (!this.supportsResponseType(URLTYPE_SEARCH_HTML))

       FAIL("_parseAsOpenSearch: No text/html result type!", Cr.NS_ERROR_FAILURE);

   },

   /**

    * Extract search engine information from the collected data to initialize

    * the engine object.

    */

   _parseAsSherlock: function SRCH_ENG_parseAsSherlock() {

     /**

      * Extracts one Sherlock "section" from aSource. A section is essentially

      * an HTML element with attributes, but each attribute must be on a new

      * line, by definition.

      *

      * @param aLines

      *        An array of lines from the sherlock file.

      * @param aSection

      *        The name of the section (e.g. "search" or "browser"). This value

      *        is not case sensitive.

      * @returns an object whose properties correspond to the section's

      *          attributes.

      */

     function getSection(aLines, aSection) {

       LOG("_parseAsSherlock::getSection: Sherlock lines:\n" +

           aLines.join("\n"));

       var lines = aLines;

       var startMark = new RegExp("^\\s*<" + aSection.toLowerCase() + "\\s*",

                                  "gi");

       var endMark   = /\s*>\s*$/gi;

       var foundStart = false;

       var startLine, numberOfLines;

       // Find the beginning and end of the section

       for (var i = 0; i < lines.length; i++) {

         if (foundStart) {

           if (endMark.test(lines[i])) {

             numberOfLines = i - startLine;

             // Remove the end marker

             lines[i] = lines[i].replace(endMark, "");

             // If the endmarker was not the only thing on the line, include

             // this line in the results

             if (lines[i])

               numberOfLines++;

             break;

           }

         } else {

           if (startMark.test(lines[i])) {

             foundStart = true;

             // Remove the start marker

             lines[i] = lines[i].replace(startMark, "");

             startLine = i;

             // If the line is empty, don't include it in the result

             if (!lines[i])

               startLine++;

           }

         }

       }

       LOG("_parseAsSherlock::getSection: Start index: " + startLine +

           "\nNumber of lines: " + numberOfLines);

       lines = lines.splice(startLine, numberOfLines);

       LOG("_parseAsSherlock::getSection: Section lines:\n" +

           lines.join("\n"));

       var section = {};

       for (var i = 0; i < lines.length; i++) {

         var line = lines[i].trim();

         var els = line.split("=");

         var name = els.shift().trim().toLowerCase();

         var value = els.join("=").trim();

         if (!name || !value)

           continue;

         // Strip leading and trailing whitespace, remove quotes from the

         // value, and remove any trailing slashes or ">" characters

         value = value.replace(/^["']/, "")

                      .replace(/["']\s*[\\\/]?>?\s*$/, "") || "";

         value = value.trim();

         // Don't clobber existing attributes

         if (!(name in section))

           section[name] = value;

       }

       return section;

     }

     /**

      * Returns an array of name-value pair arrays representing the Sherlock

      * file's input elements. User defined inputs return USER_DEFINED

      * as the value. Elements are returned in the order they appear in the

      * source file.

      *

      *   Example:

      *      <input name="foo" value="bar">

      *      <input name="foopy" user>

      *   Returns:

      *      [["foo", "bar"], ["foopy", "{searchTerms}"]]

      *

      * @param aLines

      *        An array of lines from the source file.

      */

     function getInputs(aLines) {

       /**

        * Extracts an attribute value from a given a line of text.

        *    Example: <input value="foo" name="bar">

        *      Extracts the string |foo| or |bar| given an input aAttr of

        *      |value| or |name|.

        * Attributes may be quoted or unquoted. If unquoted, any whitespace

        * indicates the end of the attribute value.

        *    Example: < value=22 33 name=44\334 >

        *      Returns |22| for "value" and |44\334| for "name".

        *

        * @param aAttr

        *        The name of the attribute for which to obtain the value. This

        *        value is not case sensitive.

        * @param aLine

        *        The line containing the attribute.

        *

        * @returns the attribute value, or an empty string if the attribute

        *          doesn't exist.

        */

       function getAttr(aAttr, aLine) {

         // Used to determine whether an "input" line from a Sherlock file is a

         // "user defined" input.

         const userInput = /(\s|["'=])user(\s|[>="'\/\\+]|$)/i;

         LOG("_parseAsSherlock::getAttr: Getting attr: \"" +

             aAttr + "\" for line: \"" + aLine + "\"");

         // We're not case sensitive, but we want to return the attribute value

         // in its original case, so create a copy of the source

         var lLine = aLine.toLowerCase();

         var attr = aAttr.toLowerCase();

         var attrStart = lLine.search(new RegExp("\\s" + attr, "i"));

         if (attrStart == -1) {

           // If this is the "user defined input" (i.e. contains the empty

           // "user" attribute), return our special keyword

           if (userInput.test(lLine) && attr == "value") {

             LOG("_parseAsSherlock::getAttr: Found user input!\nLine:\"" + lLine

                 + "\"");

             return USER_DEFINED;

           }

           // The attribute doesn't exist - ignore

           LOG("_parseAsSherlock::getAttr: Failed to find attribute:\nLine:\""

               + lLine + "\"\nAttr:\"" + attr + "\"");

           return "";

         }

         var valueStart = lLine.indexOf("=", attrStart) + "=".length;

         if (valueStart == -1)

           return "";

         var quoteStart = lLine.indexOf("\"", valueStart);

         if (quoteStart == -1) {

           // Unquoted attribute, get the rest of the line, trimmed at the first

           // sign of whitespace. If the rest of the line is only whitespace,

           // returns a blank string.

           return lLine.substr(valueStart).replace(/\s.*$/, "");

         } else {

           // Make sure that there's only whitespace between the start of the

           // value and the first quote. If there is, end the attribute value at

           // the first sign of whitespace. This prevents us from falling into

           // the next attribute if this is an unquoted attribute followed by a

           // quoted attribute.

           var betweenEqualAndQuote = lLine.substring(valueStart, quoteStart);

           if (/\S/.test(betweenEqualAndQuote))

             return lLine.substr(valueStart).replace(/\s.*$/, "");

           // Adjust the start index to account for the opening quote

           valueStart = quoteStart + "\"".length;

           // Find the closing quote

           var valueEnd = lLine.indexOf("\"", valueStart);

           // If there is no closing quote, just go to the end of the line

           if (valueEnd == -1)

             valueEnd = aLine.length;

         }

         return aLine.substring(valueStart, valueEnd);

       }

       var inputs = [];

       LOG("_parseAsSherlock::getInputs: Lines:\n" + aLines);

       // Filter out everything but non-inputs

       let lines = aLines.filter(function (line) {

         return /^\s*<input/i.test(line);

       });

       LOG("_parseAsSherlock::getInputs: Filtered lines:\n" + lines);

       lines.forEach(function (line) {

         // Strip leading/trailing whitespace and remove the surrounding markup

         // ("<input" and ">")

         line = line.trim().replace(/^<input/i, "").replace(/>$/, "");

         // If this is one of the "directional" inputs (<inputnext>/<inputprev>)

         const directionalInput = /^(prev|next)/i;

         if (directionalInput.test(line)) {

           // Make it look like a normal input by removing "prev" or "next"

           line = line.replace(directionalInput, "");

           // If it has a name, give it a dummy value to match previous

           // nsInternetSearchService behavior

           if (/name\s*=/i.test(line)) {

             line += " value=\"0\"";

           } else

             return; // Line has no name, skip it

         }

         var attrName = getAttr("name", line);

         var attrValue = getAttr("value", line);

         LOG("_parseAsSherlock::getInputs: Got input:\nName:\"" + attrName +

             "\"\nValue:\"" + attrValue + "\"");

         if (attrValue)

           inputs.push([attrName, attrValue]);

       });

       return inputs;

     }

     function err(aErr) {

       FAIL("_parseAsSherlock::err: Sherlock param error:\n" + aErr,

            Cr.NS_ERROR_FAILURE);

     }

     // First try converting our byte array using the default Sherlock encoding.

     // If this fails, or if we find a sourceTextEncoding attribute, we need to

     // reconvert the byte array using the specified encoding.

     var sherlockLines, searchSection, sourceTextEncoding, browserSection;

     try {

       sherlockLines = sherlockBytesToLines(this._data);

       searchSection = getSection(sherlockLines, "search");

       browserSection = getSection(sherlockLines, "browser");

       sourceTextEncoding = parseInt(searchSection["sourcetextencoding"]);

       if (sourceTextEncoding) {

         // Re-convert the bytes using the found sourceTextEncoding

         sherlockLines = sherlockBytesToLines(this._data, sourceTextEncoding);

         searchSection = getSection(sherlockLines, "search");

         browserSection = getSection(sherlockLines, "browser");

       }

     } catch (ex) {

       // The conversion using the default charset failed. Remove any non-ascii

       // bytes and try to find a sourceTextEncoding.

       var asciiBytes = this._data.filter(function (n) {return !(0x80 & n);});

       var asciiString = String.fromCharCode.apply(null, asciiBytes);

       sherlockLines = asciiString.split(NEW_LINES).filter(isUsefulLine);

       searchSection = getSection(sherlockLines, "search");

       sourceTextEncoding = parseInt(searchSection["sourcetextencoding"]);

       if (sourceTextEncoding) {

         sherlockLines = sherlockBytesToLines(this._data, sourceTextEncoding);

         searchSection = getSection(sherlockLines, "search");

         browserSection = getSection(sherlockLines, "browser");

       } else

         ERROR("Couldn't find a working charset", Cr.NS_ERROR_FAILURE);

     }

     LOG("_parseAsSherlock: Search section:\n" + searchSection.toSource());

     this._name = searchSection["name"] || err("Missing name!");

     this._description = searchSection["description"] || "";

     this._queryCharset = searchSection["querycharset"] ||

                          queryCharsetFromCode(searchSection["queryencoding"]);

     this._searchForm = searchSection["searchform"];

     this._updateInterval = parseInt(browserSection["updatecheckdays"]);

     this._updateURL = browserSection["update"];

     this._iconUpdateURL = browserSection["updateicon"];

     var method = (searchSection["method"] || "GET").toUpperCase();

     var template = searchSection["action"] || err("Missing action!");

     var inputs = getInputs(sherlockLines);

     LOG("_parseAsSherlock: Inputs:\n" + inputs.toSource());

     var url = null;

     if (method == "GET") {

       // Here's how we construct the input string:

       // <input> is first:  Name Attr:  Prefix      Data           Example:

       // YES                EMPTY       None        <value>        TEMPLATE<value>

       // YES                NON-EMPTY   ?           <name>=<value> TEMPLATE?<name>=<value>

       // NO                 EMPTY       ------------- <ignored> --------------

       // NO                 NON-EMPTY   &           <name>=<value> TEMPLATE?<n1>=<v1>&<n2>=<v2>

       for (var i = 0; i < inputs.length; i++) {

         var name  = inputs[i][0];

         var value = inputs[i][1];

         if (i==0) {

           if (name == "")

             template += USER_DEFINED;

           else

             template += "?" + name + "=" + value;

         } else if (name != "")

           template += "&" + name + "=" + value;

       }

       url = new EngineURL(URLTYPE_SEARCH_HTML, method, template);

     } else if (method == "POST") {

       // Create the URL object and just add the parameters directly

       url = new EngineURL(URLTYPE_SEARCH_HTML, method, template);

       for (var i = 0; i < inputs.length; i++) {

         var name  = inputs[i][0];

         var value = inputs[i][1];

         if (name)

           url.addParam(name, value);

       }

     } else

       err("Invalid method!");

     this._urls.push(url);

   },

   /**

    * Init from a JSON record.

    **/

   _initWithJSON: function SRCH_ENG__initWithJSON(aJson) {

     this.__id = aJson._id;

     this._name = aJson._name;

     this._description = aJson.description;

     if (aJson._hasPreferredIcon == undefined)

       this._hasPreferredIcon = true;

     else

       this._hasPreferredIcon = false;

     this._hidden = aJson._hidden;

     this._type = aJson.type || SEARCH_TYPE_MOZSEARCH;

     this._queryCharset = aJson.queryCharset || DEFAULT_QUERY_CHARSET;

     this.__searchForm = aJson.__searchForm;

     this.__installLocation = aJson._installLocation || SEARCH_APP_DIR;

     this._updateInterval = aJson._updateInterval || null;

     this._updateURL = aJson._updateURL || null;

     this._iconUpdateURL = aJson._iconUpdateURL || null;

     if (aJson._readOnly == undefined)

       this._readOnly = true;

     else

       this._readOnly = false;

     this._iconURI = makeURI(aJson._iconURL);

     this._iconMapObj = aJson._iconMapObj;

     for (let i = 0; i < aJson._urls.length; ++i) {

       let url = aJson._urls[i];

       let engineURL = new EngineURL(url.type || URLTYPE_SEARCH_HTML,

                                     url.method || "GET", url.template,

                                     url.resultDomain);

       engineURL._initWithJSON(url, this);

       this._urls.push(engineURL);

     }

   },

   /**

    * Creates a JavaScript object that represents this engine.

    * @param aFilter

    *        Whether or not to filter out common default values. Recommended for

    *        use with _initWithJSON().

    * @returns An object suitable for serialization as JSON.

    **/

   _serializeToJSON: function SRCH_ENG__serializeToJSON(aFilter) {

     var json = {

       _id: this._id,

       _name: this._name,

       _hidden: this.hidden,

       description: this.description,

       __searchForm: this.__searchForm,

       _iconURL: this._iconURL,

       _iconMapObj: this._iconMapObj,

       _urls: [url._serializeToJSON() for each(url in this._urls)]

     };

     if (this._file instanceof Ci.nsILocalFile)

       json.filePath = this._file.persistentDescriptor;

     if (this._uri)

       json._url = this._uri.spec;

     if (this._installLocation != SEARCH_APP_DIR || !aFilter)

       json._installLocation = this._installLocation;

     if (this._updateInterval || !aFilter)

       json._updateInterval = this._updateInterval;

     if (this._updateURL || !aFilter)

       json._updateURL = this._updateURL;

     if (this._iconUpdateURL || !aFilter)

       json._iconUpdateURL = this._iconUpdateURL;

     if (!this._hasPreferredIcon || !aFilter)

       json._hasPreferredIcon = this._hasPreferredIcon;

     if (this.type != SEARCH_TYPE_MOZSEARCH || !aFilter)

       json.type = this.type;

     if (this.queryCharset != DEFAULT_QUERY_CHARSET || !aFilter)

       json.queryCharset = this.queryCharset;

     if (this._dataType != SEARCH_DATA_XML || !aFilter)

       json._dataType = this._dataType;

     if (!this._readOnly || !aFilter)

       json._readOnly = this._readOnly;

     return json;

   },

   /**

    * Returns an XML document object containing the search plugin information,

    * which can later be used to reload the engine.

    */

   _serializeToElement: function SRCH_ENG_serializeToEl() {

     function appendTextNode(aNameSpace, aLocalName, aValue) {

       if (!aValue)

         return null;

       var node = doc.createElementNS(aNameSpace, aLocalName);

       node.appendChild(doc.createTextNode(aValue));

       docElem.appendChild(node);

       docElem.appendChild(doc.createTextNode("\n"));

       return node;

     }

     var parser = Cc["@mozilla.org/xmlextras/domparser;1"].

                  createInstance(Ci.nsIDOMParser);

     var doc = parser.parseFromString(EMPTY_DOC, "text/xml");

     var docElem = doc.documentElement;

     docElem.appendChild(doc.createTextNode("\n"));

     appendTextNode(OPENSEARCH_NS_11, "ShortName", this.name);

     appendTextNode(OPENSEARCH_NS_11, "Description", this._description);

     appendTextNode(OPENSEARCH_NS_11, "InputEncoding", this._queryCharset);

     if (this._iconURI) {

       var imageNode = appendTextNode(OPENSEARCH_NS_11, "Image",

                                      this._iconURI.spec);

       if (imageNode) {

         imageNode.setAttribute("width", "16");

         imageNode.setAttribute("height", "16");

       }

     }

     appendTextNode(MOZSEARCH_NS_10, "UpdateInterval", this._updateInterval);

     appendTextNode(MOZSEARCH_NS_10, "UpdateUrl", this._updateURL);

     appendTextNode(MOZSEARCH_NS_10, "IconUpdateUrl", this._iconUpdateURL);

     appendTextNode(MOZSEARCH_NS_10, "SearchForm", this._searchForm);

     for (var i = 0; i < this._urls.length; ++i)

       this._urls[i]._serializeToElement(doc, docElem);

     docElem.appendChild(doc.createTextNode("\n"));

     return doc;

   },

   get lazySerializeTask() {

     if (!this._lazySerializeTask) {

       let task = function taskCallback() {

         this._serializeToFile();

       }.bind(this);

       this._lazySerializeTask = new DeferredTask(task, LAZY_SERIALIZE_DELAY);

     }

     return this._lazySerializeTask;

   },

   /**

    * Serializes the engine object to file.

    */

   _serializeToFile: function SRCH_ENG_serializeToFile() {

     var file = this._file;

     ENSURE_WARN(!this._readOnly, "Can't serialize a read only engine!",

                 Cr.NS_ERROR_FAILURE);

     ENSURE_WARN(file && file.exists(), "Can't serialize: file doesn't exist!",

                 Cr.NS_ERROR_UNEXPECTED);

     var fos = Cc["@mozilla.org/network/safe-file-output-stream;1"].

               createInstance(Ci.nsIFileOutputStream);

     // Serialize the engine first - we don't want to overwrite a good file

     // if this somehow fails.

     var doc = this._serializeToElement();

     fos.init(file, (MODE_WRONLY | MODE_TRUNCATE), PERMS_FILE, 0);

     try {

       var serializer = Cc["@mozilla.org/xmlextras/xmlserializer;1"].

                        createInstance(Ci.nsIDOMSerializer);

       serializer.serializeToStream(doc.documentElement, fos, null);

     } catch (e) {

       LOG("_serializeToFile: Error serializing engine:\n" + e);

     }

     closeSafeOutputStream(fos);

     Services.obs.notifyObservers(file.clone(), SEARCH_SERVICE_TOPIC,

                                  "write-engine-to-disk-complete");

   },

   /**

    * Remove the engine's file from disk. The search service calls this once it

    * removes the engine from its internal store. This function will throw if

    * the file cannot be removed.

    */

   _remove: function SRCH_ENG_remove() {

     if (this._readOnly)

       FAIL("Can't remove read only engine!", Cr.NS_ERROR_FAILURE);

     if (!this._file || !this._file.exists())

       FAIL("Can't remove engine: file doesn't exist!", Cr.NS_ERROR_FILE_NOT_FOUND);

     this._file.remove(false);

   },

   // nsISearchEngine

   get alias() {

     if (this._alias === undefined)

       this._alias = engineMetadataService.getAttr(this, "alias");

     return this._alias;

   },

   set alias(val) {

     this._alias = val;

     engineMetadataService.setAttr(this, "alias", val);

     notifyAction(this, SEARCH_ENGINE_CHANGED);

   },

   /**

    * Return the built-in identifier of app-provided engines.

    *

    * Note that this identifier is substantially similar to _id, with the

    * following exceptions:

    *

    * * There is no trailing file extension.

    * * There is no [app] prefix.

    *

    * @return a string identifier, or null.

    */

   get identifier() {

     if (this._identifier !== undefined) {

       return this._identifier;

     }

     // No identifier if If the engine isn't app-provided

     if (!this._isInAppDir && !this._isInJAR) {

       return this._identifier = null;

     }

     let leaf = this._getLeafName();

     ENSURE_WARN(leaf, "identifier: app-provided engine has no leafName");

     // Strip file extension.

     let ext = leaf.lastIndexOf(".");

     if (ext == -1) {

       return this._identifier = leaf;

     }

     return this._identifier = leaf.substring(0, ext);

   },

   get description() {

     return this._description;

   },

   get hidden() {

     if (this._hidden === null)

       this._hidden = engineMetadataService.getAttr(this, "hidden") || false;

     return this._hidden;

   },

   set hidden(val) {

     var value = !!val;

     if (value != this._hidden) {

       this._hidden = value;

       engineMetadataService.setAttr(this, "hidden", value);

       notifyAction(this, SEARCH_ENGINE_CHANGED);

     }

   },

   get iconURI() {

     if (this._iconURI)

       return this._iconURI;

     return null;

   },

   get _iconURL() {

     if (!this._iconURI)

       return "";

     return this._iconURI.spec;

   },

   // Where the engine is being loaded from: will return the URI's spec if the

   // engine is being downloaded and does not yet have a file. This is only used

   // for logging and error messages.

   get _location() {

     if (this._file)

       return this._file.path;

     if (this._uri)

       return this._uri.spec;

     return "";

   },

   /**

    * @return the leaf name of the filename or URI of this plugin,

    *         or null if no file or URI is known.

    */

   _getLeafName: function () {

     if (this._file) {

       return this._file.leafName;

     }

     if (this._uri && this._uri instanceof Ci.nsIURL) {

       return this._uri.fileName;

     }

     return null;

   },

   // The file that the plugin is loaded from is a unique identifier for it.  We

   // use this as the identifier to store data in the sqlite database

   __id: null,

   get _id() {

     if (this.__id) {

       return this.__id;

     }

     let leafName = this._getLeafName();

     // Treat engines loaded from JARs the same way we treat app shipped

     // engines.

     // Theoretically, these could also come from extensions, but there's no

     // real way for extensions to register their chrome locations at the

     // moment, so let's not deal with that case.

     // This means we're vulnerable to conflicts if a file loaded from a JAR

     // has the same filename as a file loaded from the app dir, but with a

     // different engine name. People using the JAR functionality should be

     // careful not to do that!

     if (this._isInAppDir || this._isInJAR) {

       // App dir and JAR engines should always have leafNames

       ENSURE_WARN(leafName, "_id: no leafName for appDir or JAR engine",

                   Cr.NS_ERROR_UNEXPECTED);

       return this.__id = "[app]/" + leafName;

     }

     if (this._isInProfile) {

       ENSURE_WARN(leafName, "_id: no leafName for profile engine",

                   Cr.NS_ERROR_UNEXPECTED);

       return this.__id = "[profile]/" + leafName;

     }

     // If the engine isn't a JAR engine, it should have a file.

     ENSURE_WARN(this._file, "_id: no _file for non-JAR engine",

                 Cr.NS_ERROR_UNEXPECTED);

     // We're not in the profile or appdir, so this must be an extension-shipped

     // plugin. Use the full filename.

     return this.__id = this._file.path;

   },

   get _installLocation() {

     if (this.__installLocation === null) {

       if (!this._file) {

         ENSURE_WARN(this._uri, "Engines without files must have URIs",

                     Cr.NS_ERROR_UNEXPECTED);

         this.__installLocation = SEARCH_JAR;

       }

       else if (this._file.parent.equals(getDir(NS_APP_SEARCH_DIR)))

         this.__installLocation = SEARCH_APP_DIR;

       else if (this._file.parent.equals(getDir(NS_APP_USER_SEARCH_DIR)))

         this.__installLocation = SEARCH_PROFILE_DIR;

       else

         this.__installLocation = SEARCH_IN_EXTENSION;

     }

     return this.__installLocation;

   },

   get _isInJAR() {

     return this._installLocation == SEARCH_JAR;

   },

   get _isInAppDir() {

     return this._installLocation == SEARCH_APP_DIR;

   },

   get _isInProfile() {

     return this._installLocation == SEARCH_PROFILE_DIR;

   },

   get _isDefault() {

     // For now, our concept of a "default engine" is "one that is not in the

     // user's profile directory", which is currently equivalent to "is app- or

     // extension-shipped".

     return !this._isInProfile;

   },

   get _hasUpdates() {

     // Whether or not the engine has an update URL

     let selfURL = this._getURLOfType(URLTYPE_OPENSEARCH, "self");

     return !!(this._updateURL || this._iconUpdateURL || selfURL);

   },

   get name() {

     return this._name;

   },

   get type() {

     return this._type;

   },