misc.js

/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is Mail utility functions for GMail Conversation View
 *
 * The Initial Developer of the Original Code is
 * Jonathan Protzenko
 * Portions created by the Initial Developer are Copyright (C) 2010
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

/**
 * @fileoverview This file provides various utilities: some helpers to deal with
 * identity management, some helpers for JS programming, some helpers for
 * low-level XPCOM stuff...
 * @author Jonathan Protzenko
 */

var EXPORTED_SYMBOLS = [
  // Identity management helpers
  'gIdentities', 'fillIdentities',
  // JS programming helpers
  'range', 'MixIn',
  // XPCOM helpers
  'NS_FAILED', 'NS_SUCCEEDED',
  // Various formatting helpers
  'dateAsInMessageList', 'escapeHtml', 'parseMimeLine',
  // Useful for web content
  'encodeUrlParameters', 'decodeUrlParameters',
]

const {classes: Cc, interfaces: Ci, utils: Cu} = Components;
Cu.import("resource:///modules/iteratorUtils.jsm"); // for fixIterator
Cu.import("resource://gre/modules/XPCOMUtils.jsm");

Cu.import("resource:///modules/mailServices.js");
// That one doesn't belong to MailServices.
XPCOMUtils.defineLazyServiceGetter(MailServices, "i18nDateFormatter",
                                   "@mozilla.org/intl/scriptabledateformat;1",
                                   "nsIScriptableDateFormat");

/**
 * Low-level XPCOM-style macro. You might need this for the composition and
 *  sending listeners which will pass you some status codes.
 * @param {Int} v The status code
 * @return {Bool}
 */
function NS_FAILED(v) {
  return (v & 0x80000000);
}

/**
 * Low-level XPCOM-style macro. You might need this for the composition and
 *  sending listeners which will pass you some status codes.
 * @param {Int} v The status code
 * @return {Bool}
 */
function NS_SUCCEEDED(v) {
  return !NS_FAILED(v);
}

/**
 * Python-style range function to use in list comprehensions.
 *  @param {Number} begin 
 *  @param {Number} end 
 *  @return {Iterator} An iterator that yields from begin to end - 1.
 */
function range(begin, end) {
  for (let i = begin; i < end; ++i) {
    yield i;
  }
}

/**
 * MixIn-style helper. Adds aMixIn properties, getters and setters to
 *  aConstructor.
 * @param {Object} aConstructor
 * @param {Object} aMixIn
 */
function MixIn(aConstructor, aMixIn) {
  let proto = aConstructor.prototype;
  for (let [name, func] in Iterator(aMixIn)) {
    if (name.substring(0, 4) == "get_")
      proto.__defineGetter__(name.substring(4), func);
    else
      proto[name] = func;
  }
}

/**
 * A global pointer to all the identities known for the user. Feel free to call
 *  fillIdentities again if you feel that the user has updated them!
 * The keys are email addresses, the values are <tt>nsIMsgIdentity</tt> objects.
 *
 * @const
 */
let gIdentities = {};

/**
 * This function you should call to populate the gIdentities global object. The
 *  recommended time to call this is after the mail-startup-done event, although
 *  doing this at overlay load-time seems to be fine as well.
 * Beware, although gIdentities has a "default" key, it is not guaranteed to be
 *  non-null.
 * @param aSkipNntp (optional) Should we avoid including nntp identities in the
 *  list?
 */
function fillIdentities(aSkipNntp) {
  for each (let account in fixIterator(MailServices.accounts.accounts, Ci.nsIMsgAccount)) {
    let server = account.incomingServer;
    if (aSkipNntp && (!server || server.type != "pop3" && server.type != "imap"))
      continue;
    for each (let id in fixIterator(account.identities, Ci.nsIMsgIdentity)) {
      // We're only interested in identities that have a real email.
      if (id.email) {
        gIdentities[id.email.toLowerCase()] = id;
      }
    }
  }
  gIdentities["default"] = MailServices.accounts.defaultAccount.defaultIdentity;
}

/**
 * A stupid formatting function that uses the i18nDateFormatter XPCOM component
 * to format a date just like in the message list
 * @param {Date} aDate a javascript Date object
 * @return {String} a string containing the formatted date
 */
function dateAsInMessageList(aDate) {
  // Is it today? (Less stupid tests are welcome!)
  let format = aDate.toLocaleDateString("%x") == (new Date()).toLocaleDateString("%x")
    ? Ci.nsIScriptableDateFormat.dateFormatNone
    : Ci.nsIScriptableDateFormat.dateFormatShort;
  // That is an ugly XPCOM call!
  return MailServices.i18nDateFormatter.FormatDateTime(
    "", format, Ci.nsIScriptableDateFormat.timeFormatNoSeconds,
    aDate.getFullYear(), aDate.getMonth() + 1, aDate.getDate(),
    aDate.getHours(), aDate.getMinutes(), aDate.getSeconds());
}

/**
 * Helper function to escape some XML chars, so they display properly in
 *  innerHTML.
 * @param {String} s input text
 * @return {String} The string with &lt;, &gt;, and &amp; replaced by the corresponding entities.
 */
function escapeHtml(s) {
  s += "";
  // stolen from selectionsummaries.js (thanks davida!)
  return s.replace(/[<>&]/g, function(s) {
      switch (s) {
        case "<": return "&lt;";
        case ">": return "&gt;";
        case "&": return "&amp;";
        default: throw Error("Unexpected match");
      }
    }
  );
}

/**
 * Wraps the low-level header parser stuff.
 * @param {String} aMimeLine a line that looks like "John &lt;john@cheese.com&gt;, Jane &lt;jane@wine.com&gt;"
 * @param {Boolean} aDontFix (optional) Default to false. Shall we return an
 *  empty array in case aMimeLine is empty?
 * @return {Array} a list of { email, name } objects
 */
function parseMimeLine (aMimeLine, aDontFix) {
  let emails = {};
  let fullNames = {};
  let names = {};
  let numAddresses = MailServices.headerParser.parseHeadersWithArray(aMimeLine,
                                                                     emails,
                                                                     names,
                                                                     fullNames);
  if (numAddresses)
    return [{ email: emails.value[i], name: names.value[i], fullName: fullNames.value[i] }
      for each (i in range(0, numAddresses))];
  else if (aDontFix)
    return [];
  else
    return [{ email: "", name: "-", fullName: "-" }];
}

/**
 * Takes an object whose keys are the parameter names, whose values are strings
 * that are to be encoded in the url.
 * @param aObj
 * @return param1=val1&param2=val2 etc.
 */
function encodeUrlParameters(aObj) {
  let kv = [];
  for each (let [k, v] in Iterator(aObj)) {
    kv.push(k+"="+encodeURIComponent(v));
  }
  return kv.join("&");
}

/**
 * Takes the <b>entire</b> query string and returns an object whose keys are the
 * parameter names and values are corresponding values.
 * @param aStr The entire query string
 * @return An object that holds the decoded data
 */
function decodeUrlParameters(aStr) {
  let params = {};
  let i = aStr.indexOf("?");
  if (i >= 0) {
    let query = aStr.substring(i+1, aStr.length);
    let keyVals = query.split("&");
    for each (let [, keyVal] in Iterator(keyVals)) {
      let [key, val] = keyVal.split("=");
      val = decodeURIComponent(val);
      params[key] = val;
    }
  }
  return params;
}