toolkit/devtools/webconsole/client.js

   1 /* -*- js2-basic-offset: 2; indent-tabs-mode: nil; -*- */
   2 /* vim: set ts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 "use strict";
   8
   9 const {Cc, Ci, Cu} = require("chrome");
  10
  11 loader.lazyImporter(this, "LongStringClient", "resource://gre/modules/devtools/dbg-client.jsm");
  12
  13 /**
  14  * A WebConsoleClient is used as a front end for the WebConsoleActor that is
  15  * created on the server, hiding implementation details.
  16  *
  17  * @param object aDebuggerClient
  18  *        The DebuggerClient instance we live for.
  19  * @param string aActor
  20  *        The WebConsoleActor ID.
  21  */
  22 function WebConsoleClient(aDebuggerClient, aActor)
  23 {
  24   this._actor = aActor;
  25   this._client = aDebuggerClient;
  26   this._longStrings = {};
  27 }
  28 exports.WebConsoleClient = WebConsoleClient;
  29
  30 WebConsoleClient.prototype = {
  31   _longStrings: null,
  32
  33   /**
  34    * Retrieve the cached messages from the server.
  35    *
  36    * @see this.CACHED_MESSAGES
  37    * @param array aTypes
  38    *        The array of message types you want from the server. See
  39    *        this.CACHED_MESSAGES for known types.
  40    * @param function aOnResponse
  41    *        The function invoked when the response is received.
  42    */
  43   getCachedMessages: function WCC_getCachedMessages(aTypes, aOnResponse)
  44   {
  45     let packet = {
  46       to: this._actor,
  47       type: "getCachedMessages",
  48       messageTypes: aTypes,
  49     };
  50     this._client.request(packet, aOnResponse);
  51   },
  52
  53   /**
  54    * Inspect the properties of an object.
  55    *
  56    * @param string aActor
  57    *        The WebConsoleObjectActor ID to send the request to.
  58    * @param function aOnResponse
  59    *        The function invoked when the response is received.
  60    */
  61   inspectObjectProperties:
  62   function WCC_inspectObjectProperties(aActor, aOnResponse)
  63   {
  64     let packet = {
  65       to: aActor,
  66       type: "inspectProperties",
  67     };
  68     this._client.request(packet, aOnResponse);
  69   },
  70
  71   /**
  72    * Evaluate a JavaScript expression.
  73    *
  74    * @param string aString
  75    *        The code you want to evaluate.
  76    * @param function aOnResponse
  77    *        The function invoked when the response is received.
  78    * @param object [aOptions={}]
  79    *        Options for evaluation:
  80    *
  81    *        - bindObjectActor: an ObjectActor ID. The OA holds a reference to
  82    *        a Debugger.Object that wraps a content object. This option allows
  83    *        you to bind |_self| to the D.O of the given OA, during string
  84    *        evaluation.
  85    *
  86    *        See: Debugger.Object.evalInGlobalWithBindings() for information
  87    *        about bindings.
  88    *
  89    *        Use case: the variable view needs to update objects and it does so
  90    *        by knowing the ObjectActor it inspects and binding |_self| to the
  91    *        D.O of the OA. As such, variable view sends strings like these for
  92    *        eval:
  93    *          _self["prop"] = value;
  94    *
  95    *        - frameActor: a FrameActor ID. The FA holds a reference to
  96    *        a Debugger.Frame. This option allows you to evaluate the string in
  97    *        the frame of the given FA.
  98    *
  99    *        - url: the url to evaluate the script as. Defaults to
 100    *        "debugger eval code".
 101    */
 102   evaluateJS: function WCC_evaluateJS(aString, aOnResponse, aOptions = {})
 103   {
 104     let packet = {
 105       to: this._actor,
 106       type: "evaluateJS",
 107       text: aString,
 108       bindObjectActor: aOptions.bindObjectActor,
 109       frameActor: aOptions.frameActor,
 110       url: aOptions.url,
 111     };
 112     this._client.request(packet, aOnResponse);
 113   },
 114
 115   /**
 116    * Autocomplete a JavaScript expression.
 117    *
 118    * @param string aString
 119    *        The code you want to autocomplete.
 120    * @param number aCursor
 121    *        Cursor location inside the string. Index starts from 0.
 122    * @param function aOnResponse
 123    *        The function invoked when the response is received.
 124    * @param string aFrameActor
 125    *        The id of the frame actor that made the call.
 126    */
 127   autocomplete: function WCC_autocomplete(aString, aCursor, aOnResponse, aFrameActor)
 128   {
 129     let packet = {
 130       to: this._actor,
 131       type: "autocomplete",
 132       text: aString,
 133       cursor: aCursor,
 134       frameActor: aFrameActor,
 135     };
 136     this._client.request(packet, aOnResponse);
 137   },
 138
 139   /**
 140    * Clear the cache of messages (page errors and console API calls).
 141    */
 142   clearMessagesCache: function WCC_clearMessagesCache()
 143   {
 144     let packet = {
 145       to: this._actor,
 146       type: "clearMessagesCache",
 147     };
 148     this._client.request(packet);
 149   },
 150
 151   /**
 152    * Get Web Console-related preferences on the server.
 153    *
 154    * @param array aPreferences
 155    *        An array with the preferences you want to retrieve.
 156    * @param function [aOnResponse]
 157    *        Optional function to invoke when the response is received.
 158    */
 159   getPreferences: function WCC_getPreferences(aPreferences, aOnResponse)
 160   {
 161     let packet = {
 162       to: this._actor,
 163       type: "getPreferences",
 164       preferences: aPreferences,
 165     };
 166     this._client.request(packet, aOnResponse);
 167   },
 168
 169   /**
 170    * Set Web Console-related preferences on the server.
 171    *
 172    * @param object aPreferences
 173    *        An object with the preferences you want to change.
 174    * @param function [aOnResponse]
 175    *        Optional function to invoke when the response is received.
 176    */
 177   setPreferences: function WCC_setPreferences(aPreferences, aOnResponse)
 178   {
 179     let packet = {
 180       to: this._actor,
 181       type: "setPreferences",
 182       preferences: aPreferences,
 183     };
 184     this._client.request(packet, aOnResponse);
 185   },
 186
 187   /**
 188    * Retrieve the request headers from the given NetworkEventActor.
 189    *
 190    * @param string aActor
 191    *        The NetworkEventActor ID.
 192    * @param function aOnResponse
 193    *        The function invoked when the response is received.
 194    */
 195   getRequestHeaders: function WCC_getRequestHeaders(aActor, aOnResponse)
 196   {
 197     let packet = {
 198       to: aActor,
 199       type: "getRequestHeaders",
 200     };
 201     this._client.request(packet, aOnResponse);
 202   },
 203
 204   /**
 205    * Retrieve the request cookies from the given NetworkEventActor.
 206    *
 207    * @param string aActor
 208    *        The NetworkEventActor ID.
 209    * @param function aOnResponse
 210    *        The function invoked when the response is received.
 211    */
 212   getRequestCookies: function WCC_getRequestCookies(aActor, aOnResponse)
 213   {
 214     let packet = {
 215       to: aActor,
 216       type: "getRequestCookies",
 217     };
 218     this._client.request(packet, aOnResponse);
 219   },
 220
 221   /**
 222    * Retrieve the request post data from the given NetworkEventActor.
 223    *
 224    * @param string aActor
 225    *        The NetworkEventActor ID.
 226    * @param function aOnResponse
 227    *        The function invoked when the response is received.
 228    */
 229   getRequestPostData: function WCC_getRequestPostData(aActor, aOnResponse)
 230   {
 231     let packet = {
 232       to: aActor,
 233       type: "getRequestPostData",
 234     };
 235     this._client.request(packet, aOnResponse);
 236   },
 237
 238   /**
 239    * Retrieve the response headers from the given NetworkEventActor.
 240    *
 241    * @param string aActor
 242    *        The NetworkEventActor ID.
 243    * @param function aOnResponse
 244    *        The function invoked when the response is received.
 245    */
 246   getResponseHeaders: function WCC_getResponseHeaders(aActor, aOnResponse)
 247   {
 248     let packet = {
 249       to: aActor,
 250       type: "getResponseHeaders",
 251     };
 252     this._client.request(packet, aOnResponse);
 253   },
 254
 255   /**
 256    * Retrieve the response cookies from the given NetworkEventActor.
 257    *
 258    * @param string aActor
 259    *        The NetworkEventActor ID.
 260    * @param function aOnResponse
 261    *        The function invoked when the response is received.
 262    */
 263   getResponseCookies: function WCC_getResponseCookies(aActor, aOnResponse)
 264   {
 265     let packet = {
 266       to: aActor,
 267       type: "getResponseCookies",
 268     };
 269     this._client.request(packet, aOnResponse);
 270   },
 271
 272   /**
 273    * Retrieve the response content from the given NetworkEventActor.
 274    *
 275    * @param string aActor
 276    *        The NetworkEventActor ID.
 277    * @param function aOnResponse
 278    *        The function invoked when the response is received.
 279    */
 280   getResponseContent: function WCC_getResponseContent(aActor, aOnResponse)
 281   {
 282     let packet = {
 283       to: aActor,
 284       type: "getResponseContent",
 285     };
 286     this._client.request(packet, aOnResponse);
 287   },
 288
 289   /**
 290    * Retrieve the timing information for the given NetworkEventActor.
 291    *
 292    * @param string aActor
 293    *        The NetworkEventActor ID.
 294    * @param function aOnResponse
 295    *        The function invoked when the response is received.
 296    */
 297   getEventTimings: function WCC_getEventTimings(aActor, aOnResponse)
 298   {
 299     let packet = {
 300       to: aActor,
 301       type: "getEventTimings",
 302     };
 303     this._client.request(packet, aOnResponse);
 304   },
 305
 306   /**
 307    * Send a HTTP request with the given data.
 308    *
 309    * @param string aData
 310    *        The details of the HTTP request.
 311    * @param function aOnResponse
 312    *        The function invoked when the response is received.
 313    */
 314   sendHTTPRequest: function WCC_sendHTTPRequest(aData, aOnResponse) {
 315     let packet = {
 316       to: this._actor,
 317       type: "sendHTTPRequest",
 318       request: aData
 319     };
 320     this._client.request(packet, aOnResponse);
 321   },
 322
 323   /**
 324    * Start the given Web Console listeners.
 325    *
 326    * @see this.LISTENERS
 327    * @param array aListeners
 328    *        Array of listeners you want to start. See this.LISTENERS for
 329    *        known listeners.
 330    * @param function aOnResponse
 331    *        Function to invoke when the server response is received.
 332    */
 333   startListeners: function WCC_startListeners(aListeners, aOnResponse)
 334   {
 335     let packet = {
 336       to: this._actor,
 337       type: "startListeners",
 338       listeners: aListeners,
 339     };
 340     this._client.request(packet, aOnResponse);
 341   },
 342
 343   /**
 344    * Stop the given Web Console listeners.
 345    *
 346    * @see this.LISTENERS
 347    * @param array aListeners
 348    *        Array of listeners you want to stop. See this.LISTENERS for
 349    *        known listeners.
 350    * @param function aOnResponse
 351    *        Function to invoke when the server response is received.
 352    */
 353   stopListeners: function WCC_stopListeners(aListeners, aOnResponse)
 354   {
 355     let packet = {
 356       to: this._actor,
 357       type: "stopListeners",
 358       listeners: aListeners,
 359     };
 360     this._client.request(packet, aOnResponse);
 361   },
 362
 363   /**
 364    * Return an instance of LongStringClient for the given long string grip.
 365    *
 366    * @param object aGrip
 367    *        The long string grip returned by the protocol.
 368    * @return object
 369    *         The LongStringClient for the given long string grip.
 370    */
 371   longString: function WCC_longString(aGrip)
 372   {
 373     if (aGrip.actor in this._longStrings) {
 374       return this._longStrings[aGrip.actor];
 375     }
 376
 377     let client = new LongStringClient(this._client, aGrip);
 378     this._longStrings[aGrip.actor] = client;
 379     return client;
 380   },
 381
 382   /**
 383    * Close the WebConsoleClient. This stops all the listeners on the server and
 384    * detaches from the console actor.
 385    *
 386    * @param function aOnResponse
 387    *        Function to invoke when the server response is received.
 388    */
 389   close: function WCC_close(aOnResponse)
 390   {
 391     this.stopListeners(null, aOnResponse);
 392     this._longStrings = null;
 393     this._client = null;
 394   },
 395 };