The Tor Browser: toolkit/devtools/server/actors/root.js@6474c204b198 (annotated)

toolkit/devtools/server/actors/root.js@6474c204b198 (annotated)

toolkit/devtools/server/actors/root.js

Wed, 31 Dec 2014 06:09:35 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Wed, 31 Dec 2014 06:09:35 +0100
changeset 0: 6474c204b198
permissions: -rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

 /* -*- tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
 /* vim: set ft=javascript ts=2 et sw=2 tw=80: */
 /* 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/. */
 "use strict";
 let devtools_ = Cu.import("resource://gre/modules/devtools/Loader.jsm", {}).devtools;
 let { createExtraActors, appendExtraActors } = devtools_.require("devtools/server/actors/common");
 /* Root actor for the remote debugging protocol. */
 /**
  * Create a remote debugging protocol root actor.
  *
  * @param aConnection
  *     The DebuggerServerConnection whose root actor we are constructing.
  *
  * @param aParameters
  *     The properties of |aParameters| provide backing objects for the root
  *     actor's requests; if a given property is omitted from |aParameters|, the
  *     root actor won't implement the corresponding requests or notifications.
  *     Supported properties:
  *
  *     - tabList: a live list (see below) of tab actors. If present, the
  *       new root actor supports the 'listTabs' request, providing the live
  *       list's elements as its tab actors, and sending 'tabListChanged'
  *       notifications when the live list's contents change. One actor in
  *       this list must have a true '.selected' property.
  *
  *     - addonList: a live list (see below) of addon actors. If present, the
  *       new root actor supports the 'listAddons' request, providing the live
  *       list's elements as its addon actors, and sending 'addonListchanged'
  *       notifications when the live list's contents change.
  *
  *     - globalActorFactories: an object |A| describing further actors to
  *       attach to the 'listTabs' reply. This is the type accumulated by
  *       DebuggerServer.addGlobalActor. For each own property |P| of |A|,
  *       the root actor adds a property named |P| to the 'listTabs'
  *       reply whose value is the name of an actor constructed by
  *       |A[P]|.
  *
  *     - onShutdown: a function to call when the root actor is disconnected.
  *
  * Instance properties:
  *
  * - applicationType: the string the root actor will include as the
  *      "applicationType" property in the greeting packet. By default, this
  *      is "browser".
  *
  * Live lists:
  *
  * A "live list", as used for the |tabList|, is an object that presents a
  * list of actors, and also notifies its clients of changes to the list. A
  * live list's interface is two properties:
  *
  * - getList: a method that returns a promise to the contents of the list.
  *
  * - onListChanged: a handler called, with no arguments, when the set of
  *             values the iterator would produce has changed since the last
  *             time 'iterator' was called. This may only be set to null or a
  *             callable value (one for which the typeof operator returns
  *             'function'). (Note that the live list will not call the
  *             onListChanged handler until the list has been iterated over
  *             once; if nobody's seen the list in the first place, nobody
  *             should care if its contents have changed!)
  *
  * When the list changes, the list implementation should ensure that any
  * actors yielded in previous iterations whose referents (tabs) still exist
  * get yielded again in subsequent iterations. If the underlying referent
  * is the same, the same actor should be presented for it.
  *
  * The root actor registers an 'onListChanged' handler on the appropriate
  * list when it may need to send the client 'tabListChanged' notifications,
  * and is careful to remove the handler whenever it does not need to send
  * such notifications (including when it is disconnected). This means that
  * live list implementations can use the state of the handler property (set
  * or null) to install and remove observers and event listeners.
  *
  * Note that, as the only way for the root actor to see the members of the
  * live list is to begin an iteration over the list, the live list need not
  * actually produce any actors until they are reached in the course of
  * iteration: alliterative lazy live lists.
  */
 function RootActor(aConnection, aParameters) {
   this.conn = aConnection;
   this._parameters = aParameters;
   this._onTabListChanged = this.onTabListChanged.bind(this);
   this._onAddonListChanged = this.onAddonListChanged.bind(this);
   this._extraActors = {};
 }
 RootActor.prototype = {
   constructor: RootActor,
   applicationType: "browser",
   /**
    * Return a 'hello' packet as specified by the Remote Debugging Protocol.
    */
   sayHello: function() {
     return {
       from: this.actorID,
       applicationType: this.applicationType,
       /* This is not in the spec, but it's used by tests. */
       testConnectionPrefix: this.conn.prefix,
       traits: {
         sources: true,
         editOuterHTML: true,
         // Wether the server-side highlighter actor exists and can be used to
         // remotely highlight nodes (see server/actors/highlighter.js)
         highlightable: true,
         // Wether the inspector actor implements the getImageDataFromURL
         // method that returns data-uris for image URLs. This is used for image
         // tooltips for instance
         urlToImageDataResolver: true,
         networkMonitor: true,
         // Wether the storage inspector actor to inspect cookies, etc.
         storageInspector: true,
         // Wether storage inspector is read only
         storageInspectorReadOnly: true,
         // Wether conditional breakpoints are supported
         conditionalBreakpoints: true
       }
     };
   },
   /**
    * This is true for the root actor only, used by some child actors
    */
   get isRootActor() true,
   /**
    * The (chrome) window, for use by child actors
    */
   get window() Services.wm.getMostRecentWindow(DebuggerServer.chromeWindowType),
   /**
    * URL of the chrome window.
    */
   get url() { return this.window ? this.window.document.location.href : null; },
   /**
    * Getter for the best nsIWebProgress for to watching this window.
    */
   get webProgress() {
     return this.window
       .QueryInterface(Ci.nsIInterfaceRequestor)
       .getInterface(Ci.nsIDocShell)
       .QueryInterface(Ci.nsIInterfaceRequestor)
       .getInterface(Ci.nsIWebProgress);
   },
   /**
    * Disconnects the actor from the browser window.
    */
   disconnect: function() {
     /* Tell the live lists we aren't watching any more. */
     if (this._parameters.tabList) {
       this._parameters.tabList.onListChanged = null;
     }
     if (this._parameters.addonList) {
       this._parameters.addonList.onListChanged = null;
     }
     if (typeof this._parameters.onShutdown === 'function') {
       this._parameters.onShutdown();
     }
     this._extraActors = null;
   },
   /* The 'listTabs' request and the 'tabListChanged' notification. */
   /**
    * Handles the listTabs request. The actors will survive until at least
    * the next listTabs request.
    */
   onListTabs: function() {
     let tabList = this._parameters.tabList;
     if (!tabList) {
       return { from: this.actorID, error: "noTabs",
                message: "This root actor has no browser tabs." };
     }
     /*
      * Walk the tab list, accumulating the array of tab actors for the
      * reply, and moving all the actors to a new ActorPool. We'll
      * replace the old tab actor pool with the one we build here, thus
      * retiring any actors that didn't get listed again, and preparing any
      * new actors to receive packets.
      */
     let newActorPool = new ActorPool(this.conn);
     let tabActorList = [];
     let selected;
     return tabList.getList().then((tabActors) => {
       for (let tabActor of tabActors) {
         if (tabActor.selected) {
           selected = tabActorList.length;
         }
         tabActor.parentID = this.actorID;
         newActorPool.addActor(tabActor);
         tabActorList.push(tabActor);
       }
       /* DebuggerServer.addGlobalActor support: create actors. */
       if (!this._globalActorPool) {
         this._globalActorPool = new ActorPool(this.conn);
         this._createExtraActors(this._parameters.globalActorFactories, this._globalActorPool);
         this.conn.addActorPool(this._globalActorPool);
       }
       /*
        * Drop the old actorID -> actor map. Actors that still mattered were
        * added to the new map; others will go away.
        */
       if (this._tabActorPool) {
         this.conn.removeActorPool(this._tabActorPool);
       }
       this._tabActorPool = newActorPool;
       this.conn.addActorPool(this._tabActorPool);
       let reply = {
         "from": this.actorID,
         "selected": selected || 0,
         "tabs": [actor.form() for (actor of tabActorList)],
       };
       /* If a root window is accessible, include its URL. */
       if (this.url) {
         reply.url = this.url;
       }
       /* DebuggerServer.addGlobalActor support: name actors in 'listTabs' reply. */
       this._appendExtraActors(reply);
       /*
        * Now that we're actually going to report the contents of tabList to
        * the client, we're responsible for letting the client know if it
        * changes.
        */
       tabList.onListChanged = this._onTabListChanged;
       return reply;
     });
   },
   onTabListChanged: function () {
     this.conn.send({ from: this.actorID, type:"tabListChanged" });
     /* It's a one-shot notification; no need to watch any more. */
     this._parameters.tabList.onListChanged = null;
   },
   onListAddons: function () {
     let addonList = this._parameters.addonList;
     if (!addonList) {
       return { from: this.actorID, error: "noAddons",
                message: "This root actor has no browser addons." };
     }
     return addonList.getList().then((addonActors) => {
       let addonActorPool = new ActorPool(this.conn);
       for (let addonActor of addonActors) {
           addonActorPool.addActor(addonActor);
       }
       if (this._addonActorPool) {
         this.conn.removeActorPool(this._addonActorPool);
       }
       this._addonActorPool = addonActorPool;
       this.conn.addActorPool(this._addonActorPool);
       addonList.onListChanged = this._onAddonListChanged;
       return {
         "from": this.actorID,
         "addons": [addonActor.form() for (addonActor of addonActors)]
       };
     });
   },
   onAddonListChanged: function () {
     this.conn.send({ from: this.actorID, type: "addonListChanged" });
     this._parameters.addonList.onListChanged = null;
   },
   /* This is not in the spec, but it's used by tests. */
   onEcho: function (aRequest) {
     /*
      * Request packets are frozen. Copy aRequest, so that
      * DebuggerServerConnection.onPacket can attach a 'from' property.
      */
     return JSON.parse(JSON.stringify(aRequest));
   },
   onProtocolDescription: function (aRequest) {
     return protocol.dumpProtocolSpec()
   },
   /* Support for DebuggerServer.addGlobalActor. */
   _createExtraActors: createExtraActors,
   _appendExtraActors: appendExtraActors,
   /* ThreadActor hooks. */
   /**
    * Prepare to enter a nested event loop by disabling debuggee events.
    */
   preNest: function() {
     // Disable events in all open windows.
     let e = Services.wm.getEnumerator(null);
     while (e.hasMoreElements()) {
       let win = e.getNext();
       let windowUtils = win.QueryInterface(Ci.nsIInterfaceRequestor)
                            .getInterface(Ci.nsIDOMWindowUtils);
       windowUtils.suppressEventHandling(true);
       windowUtils.suspendTimeouts();
     }
   },
   /**
    * Prepare to exit a nested event loop by enabling debuggee events.
    */
   postNest: function(aNestData) {
     // Enable events in all open windows.
     let e = Services.wm.getEnumerator(null);
     while (e.hasMoreElements()) {
       let win = e.getNext();
       let windowUtils = win.QueryInterface(Ci.nsIInterfaceRequestor)
                            .getInterface(Ci.nsIDOMWindowUtils);
       windowUtils.resumeTimeouts();
       windowUtils.suppressEventHandling(false);
     }
   }
 };
 RootActor.prototype.requestTypes = {
   "listTabs": RootActor.prototype.onListTabs,
   "listAddons": RootActor.prototype.onListAddons,
   "echo": RootActor.prototype.onEcho,
   "protocolDescription": RootActor.prototype.onProtocolDescription
 };