User:Ehsan/PrivateBrowsingForExtensions

Introduction

Many extensions may store data which can reveal information about user's browsing history. For example, and extension may record the last visit date for all the websites that the user visits. There is currently no reliable way for us to disable storing such data by extensions, therefore it is very important to provide simple to use APIs as well as code samples which extension developers can use to integrate the Private Browsing mode with their extensions.

APIs for Extensions

The Private Browsing service

The Private Browsing service can be used in order to get and set the current status of private browsing. It supports the nsIPrivateBrowsingService interface:

[scriptable, uuid(d2943870-c781-11dc-95ff-0800200c9a66)]
interface nsIPrivateBrowsingService : nsISupports
{
    // Whether or not the private browsing mode is currently active.
    attribute boolean privateBrowsing;
};

You can use the following code sample in order to get the current status of the private browsing mode, or change it.

var pbs = Components.classes["@mozilla.org/privatebrowsing-service;1"]
                    .getService(Components.interfaces.nsIPrivateBrowsingService);
// are we currently in the Private Browsing mode?
var inPrivateBrowsingMode = pbs.privateBrowsing;

// enter the Private Browsing mode
pbs.privateBrowsing = true;

// now, whatever we do remains private!

// exit the Private Browsing mode
pbs.privateBrowsing = false;

Private Browsing notifications

Extensions can be notified of private browsing status changes, i.e., when the user enters or leaves the private browsing mode. This is done via standard XPCOM observer service mechanisms. The notification's name is "browser:private-browsing". The data parameter can be either "enter" (indicating that the private browsing mode has been initiated) or "exit" (indicating that the private browsing mode has been terminated).

You can use the following code sample in order to create a listener for the private browsing mode changes notification.

function PrivateBrowsingListener() {
  this.init();
}

PrivateBrowsingListener.prototype = {
  _os: null,
  _inPrivateBrowsing: false, // whether we are in private browsing mode
  _inited: false,
  _watcher: null, // the watcher object

  QueryInterface : function (iid) {
    if (iid.equals(Components.interfaces.nsISupports) ||
        iid.equals(Components.interfaces.nsIObserver))
      return this;

    throw Components.results.NS_ERROR_NO_INTERFACE;
  },

  init : function () {
    if (!this._inited) {
      this._inited = true;
      this._os = Components.classes["@mozilla.org/observer-service;1"]
                           .getService(Components.interfaces.nsIObserverService);
      this._os.addObserver(this, "browser:private-browsing", false);
      this._os.addObserver(this, "quit-application", false);
    }
  },

  observe : function (aSubject, aTopic, aData) {
    if (aTopic == "browser:private-browsing") {
      if (aData == "enter") {
        this._inPrivateBrowsing = true;
        if (this.watcher &&
            "onEnterPrivateBrowsing" in this._watcher) {
          this.watcher.onEnterPrivateBrowsing();
        }
      } else if (aData == "exit") {
        this._inPrivateBrowsing = false;
        if (this.watcher &&
            "onExitPrivateBrowsing" in this._watcher) {
          this.watcher.onExitPrivateBrowsing();
        }
      }
    } else if (aTopic == "quit-application") {
      this._os.removeObserver(this, "quit-application");
      this._os.removeObserver(this, "browser:private-browsing");
    }
  },

  get inPrivateBrowsing() {
    return this._inPrivateBrowsing;
  },

  get watcher() {
    return this._watcher;
  },

  set watcher(val) {
    this._watcher = val;
  }
};

var listener = PrivateBrowsingListener();

if (listener.inPrivateBrowsing) {
  // we are in the private mode!
} else {
  // we are not in the private mode!
}

listener.watcher = {
  onEnterPrivateBrowsing : function() {
    // we have just entered the private browsing mode!
  },

  onExitPrivateBrowsing : function() {
    // we have just left the private browsing mode!
  }
};