Home | History | Annotate | Download | only in renderer 
      1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
      2 // Use of this source code is governed by a BSD-style license that can be
      3 // found in the LICENSE file.
      4 
      5 #ifndef CONTENT_RENDERER_DOM_AUTOMATION_CONTROLLER_H_
      6 #define CONTENT_RENDERER_DOM_AUTOMATION_CONTROLLER_H_
      7 
      8 #include "base/basictypes.h"
      9 #include "content/public/renderer/render_frame_observer.h"
     10 #include "gin/wrappable.h"
     11 
     12 /* DomAutomationController class:
     13    Bound to Javascript window.domAutomationController object.
     14    At the very basic, this object makes any native value (string, numbers,
     15    boolean) from javascript available to the automation host in Cpp.
     16    Any renderer implementation that is built with this binding will allow the
     17    above facility.
     18    The intended use of this object is to expose the DOM Objects and their
     19    attributes to the automation host.
     20 
     21    A typical usage would be like following (JS code):
     22 
     23    var object = document.getElementById('some_id');
     24    window.domAutomationController.send(object.nodeName); // get the tag name
     25 
     26    For the exact mode of usage,
     27    refer AutomationProxyTest.*DomAutomationController tests.
     28 
     29    The class provides a single send method that can send variety of native
     30    javascript values. (NPString, Number(double), Boolean)
     31 
     32    The actual communication occurs in the following manner:
     33 
     34     TEST            MASTER          RENDERER
     35               (1)             (3)
     36    |AProxy| ----->|AProvider|----->|RenderView|------|
     37       /\                |               |            |
     38       |                 |               |            |
     39       |(6)              |(2)            |(0)         |(4)
     40       |                 |               \/           |
     41       |                 |-------->|DAController|<----|
     42       |                                 |
     43       |                                 |(5)
     44       |-------|WebContentsImpl|<--------|
     45 
     46 
     47    Legends:
     48    - AProxy = AutomationProxy
     49    - AProvider = AutomationProvider
     50    - DAController = DomAutomationController
     51 
     52    (0) Initialization step where DAController is bound to the renderer
     53        and the view_id of the renderer is supplied to the DAController for
     54        routing message in (5).
     55    (1) A 'javascript:' url is sent from the test process to master as an IPC
     56        message. A unique routing id is generated at this stage (automation_id_)
     57    (2) The automation_id_ of step (1) is supplied to DAController by calling
     58        the bound method setAutomationId(). This is required for routing message
     59        in (6).
     60    (3) The 'javascript:' url is sent for execution by calling into
     61        Browser::LoadURL()
     62    (4) A callback is generated as a result of domAutomationController.send()
     63        into Cpp. The supplied value is received as a result of this callback.
     64    (5) The value received in (4) is sent to the master along with the
     65        stored automation_id_ as an IPC message. The frame_'s RenderFrameImpl is
     66        used to route the message. (IPC messages, ViewHostMsg_*DomAutomation* )
     67    (6) The value and the automation_id_ is extracted out of the message received
     68        in (5). This value is relayed to AProxy using another IPC message.
     69        automation_id_ is used to route the message.
     70        (IPC messages, AutomationMsg_Dom*Response)
     71 
     72 */
     73 
     74 namespace blink {
     75 class WebFrame;
     76 }
     77 
     78 namespace gin {
     79 class Arguments;
     80 }
     81 
     82 namespace content {
     83 
     84 class RenderFrame;
     85 
     86 class DomAutomationController : public gin::Wrappable<DomAutomationController>,
     87                                 public RenderFrameObserver {
     88  public:
     89   static gin::WrapperInfo kWrapperInfo;
     90 
     91   static void Install(RenderFrame* render_frame, blink::WebFrame* frame);
     92 
     93   // Makes the renderer send a javascript value to the app.
     94   // The value to be sent can be either of type String,
     95   // Number (double casted to int32) or Boolean. Any other type or no
     96   // argument at all is ignored.
     97   bool SendMsg(const gin::Arguments& args);
     98 
     99   // Makes the renderer send a javascript value to the app.
    100   // The value should be properly formed JSON.
    101   bool SendJSON(const std::string& json);
    102 
    103   // Sends a string with a provided Automation Id.
    104   bool SendWithId(int automation_id, const std::string& str);
    105 
    106   bool SetAutomationId(int automation_id);
    107 
    108  private:
    109   explicit DomAutomationController(RenderFrame* render_view);
    110   virtual ~DomAutomationController();
    111 
    112   // gin::WrappableBase
    113   virtual gin::ObjectTemplateBuilder GetObjectTemplateBuilder(
    114       v8::Isolate* isolate) OVERRIDE;
    115 
    116   // RenderViewObserver
    117   virtual void OnDestruct() OVERRIDE;
    118 
    119   int automation_id_;  // routing id to be used by the next channel.
    120 
    121   DISALLOW_COPY_AND_ASSIGN(DomAutomationController);
    122 };
    123 
    124 }  // namespace content
    125 
    126 #endif  // CONTENT_RENDERER_DOM_AUTOMATION_CONTROLLER_H_
    127