content/public/browser/devtools_agent_host.h

   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_PUBLIC_BROWSER_DEVTOOLS_AGENT_HOST_H_
   6 #define CONTENT_PUBLIC_BROWSER_DEVTOOLS_AGENT_HOST_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 #include "base/basictypes.h"
  12 #include "base/callback.h"
  13 #include "base/memory/ref_counted.h"
  14 #include "base/memory/scoped_ptr.h"
  15 #include "content/common/content_export.h"
  16 #include "content/public/browser/devtools_agent_host_client.h"
  17 #include "url/gurl.h"
  18
  19 namespace base {
  20 class SingleThreadTaskRunner;
  21 }
  22
  23 namespace net {
  24 class ServerSocket;
  25 }
  26
  27 namespace content {
  28
  29 class BrowserContext;
  30 class DevToolsExternalAgentProxyDelegate;
  31 class WebContents;
  32
  33 // Describes interface for managing devtools agents from browser process.
  34 class CONTENT_EXPORT DevToolsAgentHost
  35     : public base::RefCounted<DevToolsAgentHost> {
  36  public:
  37   enum Type {
  38     // Agent host associated with WebContents.
  39     TYPE_WEB_CONTENTS,
  40
  41     // Agent host associated with RenderFrameHost.
  42     TYPE_FRAME,
  43
  44     // Agent host associated with shared worker.
  45     TYPE_SHARED_WORKER,
  46
  47     // Agent host associated with service worker.
  48     TYPE_SERVICE_WORKER,
  49
  50     // Agent host associated with DevToolsExternalAgentProxyDelegate.
  51     TYPE_EXTERNAL,
  52
  53     // Agent host associated with browser.
  54     TYPE_BROWSER,
  55   };
  56
  57   // Latest DevTools protocol version supported.
  58   static std::string GetProtocolVersion();
  59
  60   // Returns whether particular version of DevTools protocol is supported.
  61   static bool IsSupportedProtocolVersion(const std::string& version);
  62
  63   // Returns DevToolsAgentHost with a given |id| or nullptr of it doesn't exist.
  64   static scoped_refptr<DevToolsAgentHost> GetForId(const std::string& id);
  65
  66   // Returns DevToolsAgentHost that can be used for inspecting |web_contents|.
  67   // New DevToolsAgentHost will be created if it does not exist.
  68   static scoped_refptr<DevToolsAgentHost> GetOrCreateFor(
  69       WebContents* web_contents);
  70
  71   // Returns true iff an instance of DevToolsAgentHost for the |web_contents|
  72   // does exist.
  73   static bool HasFor(WebContents* web_contents);
  74
  75   // Returns DevToolsAgentHost that can be used for inspecting shared worker
  76   // with given worker process host id and routing id.
  77   static scoped_refptr<DevToolsAgentHost> GetForWorker(int worker_process_id,
  78                                                        int worker_route_id);
  79
  80   // Creates DevToolsAgentHost that communicates to the target by means of
  81   // provided |delegate|. |delegate| ownership is passed to the created agent
  82   // host.
  83   static scoped_refptr<DevToolsAgentHost> Create(
  84       DevToolsExternalAgentProxyDelegate* delegate);
  85
  86   using CreateServerSocketCallback =
  87       base::Callback<scoped_ptr<net::ServerSocket>(std::string*)>;
  88
  89   // Creates DevToolsAgentHost for the browser, which works with browser-wide
  90   // debugging protocol.
  91   static scoped_refptr<DevToolsAgentHost> CreateForBrowser(
  92       scoped_refptr<base::SingleThreadTaskRunner> tethering_task_runner,
  93       const CreateServerSocketCallback& socket_callback);
  94
  95   static bool IsDebuggerAttached(WebContents* web_contents);
  96
  97   typedef std::vector<scoped_refptr<DevToolsAgentHost> > List;
  98
  99   // Returns all possible DevToolsAgentHosts.
 100   static List GetOrCreateAll();
 101
 102   // Client attaches to this agent host to start debugging it.
 103   virtual void AttachClient(DevToolsAgentHostClient* client) = 0;
 104
 105   // Already attached client detaches from this agent host to stop debugging it.
 106   virtual void DetachClient() = 0;
 107
 108   // Returns true if there is a client attached.
 109   virtual bool IsAttached() = 0;
 110
 111   // Sends a message to the agent. Returns true if the message is handled.
 112   virtual bool DispatchProtocolMessage(const std::string& message) = 0;
 113
 114   // Starts inspecting element at position (|x|, |y|) in the specified page.
 115   virtual void InspectElement(int x, int y) = 0;
 116
 117   // Returns the unique id of the agent.
 118   virtual std::string GetId() = 0;
 119
 120   // Returns web contents instance for this host if any.
 121   virtual WebContents* GetWebContents() = 0;
 122
 123   // Returns related browser context instance if available.
 124   virtual BrowserContext* GetBrowserContext() = 0;
 125
 126   // Temporarily detaches render view host from this host. Must be followed by
 127   // a call to ConnectWebContents (may leak the host instance otherwise).
 128   virtual void DisconnectWebContents() = 0;
 129
 130   // Attaches render view host to this host.
 131   virtual void ConnectWebContents(WebContents* web_contents) = 0;
 132
 133   // Returns agent host type.
 134   virtual Type GetType() = 0;
 135
 136   // Returns agent host title.
 137   virtual std::string GetTitle() = 0;
 138
 139   // Returns url associated with agent host.
 140   virtual GURL GetURL() = 0;
 141
 142   // Activates agent host. Returns false if the operation failed.
 143   virtual bool Activate() = 0;
 144
 145   // Closes agent host. Returns false if the operation failed.
 146   virtual bool Close() = 0;
 147
 148   // Terminates all debugging sessions and detaches all clients.
 149   static void DetachAllClients();
 150
 151   typedef base::Callback<void(DevToolsAgentHost*, bool attached)>
 152       AgentStateCallback;
 153
 154   static void AddAgentStateCallback(const AgentStateCallback& callback);
 155   static void RemoveAgentStateCallback(const AgentStateCallback& callback);
 156
 157  protected:
 158   friend class base::RefCounted<DevToolsAgentHost>;
 159   virtual ~DevToolsAgentHost() {}
 160 };
 161
 162 }  // namespace content
 163
 164 #endif  // CONTENT_PUBLIC_BROWSER_DEVTOOLS_AGENT_HOST_H_