web_contents_observer.h revision 58537e28ecd584eab876aee8be7156509866d23a
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_WEB_CONTENTS_OBSERVER_H_ 6#define CONTENT_PUBLIC_BROWSER_WEB_CONTENTS_OBSERVER_H_ 7 8#include "base/process/kill.h" 9#include "base/process/process_handle.h" 10#include "content/common/content_export.h" 11#include "content/public/browser/navigation_controller.h" 12#include "content/public/common/page_transition_types.h" 13#include "ipc/ipc_listener.h" 14#include "ipc/ipc_sender.h" 15#include "ui/base/window_open_disposition.h" 16 17namespace content { 18 19class RenderViewHost; 20class WebContents; 21class WebContentsImpl; 22struct FaviconURL; 23struct FrameNavigateParams; 24struct LoadCommittedDetails; 25struct LoadFromMemoryCacheDetails; 26struct Referrer; 27struct ResourceRedirectDetails; 28struct ResourceRequestDetails; 29 30// An observer API implemented by classes which are interested in various page 31// load events from WebContents. They also get a chance to filter IPC messages. 32// 33// Since a WebContents can be a delegate to almost arbitrarily many 34// RenderViewHosts, it is important to check in those WebContentsObserver 35// methods which take a RenderViewHost that the event came from the 36// RenderViewHost the observer cares about. 37// 38// Usually, observers should only care about the current RenderViewHost as 39// returned by GetRenderViewHost(). 40// 41// TODO(creis, jochen): Hide the fact that there are several RenderViewHosts 42// from the WebContentsObserver API. http://crbug.com/173325 43class CONTENT_EXPORT WebContentsObserver : public IPC::Listener, 44 public IPC::Sender { 45 public: 46 // Only one of the two methods below will be called when a RVH is created for 47 // a WebContents, depending on whether it's for an interstitial or not. 48 virtual void RenderViewCreated(RenderViewHost* render_view_host) {} 49 virtual void RenderViewForInterstitialPageCreated( 50 RenderViewHost* render_view_host) {} 51 52 // This method is invoked when the RenderView of the current RenderViewHost 53 // is ready, e.g. because we recreated it after a crash. 54 virtual void RenderViewReady() {} 55 56 // This method is invoked when a RenderViewHost of the WebContents is 57 // deleted. Note that this does not always happen when the WebContents starts 58 // to use a different RenderViewHost, as the old RenderViewHost might get 59 // just swapped out. 60 virtual void RenderViewDeleted(RenderViewHost* render_view_host) {} 61 62 // This method is invoked when the process for the current RenderView crashes. 63 // The WebContents continues to use the RenderViewHost, e.g. when the user 64 // reloads the current page. 65 // When the RenderViewHost is deleted, the RenderViewDeleted method will be 66 // invoked. 67 virtual void RenderProcessGone(base::TerminationStatus status) {} 68 69 // This method is invoked when a WebContents swaps its render view host with 70 // another one, possibly changing processes. The RenderViewHost that has 71 // been replaced is in |old_render_view_host|, which is NULL if the old RVH 72 // was shut down. 73 virtual void RenderViewHostSwapped(RenderViewHost* old_render_view_host) {} 74 75 // This method is invoked after the WebContents decided which RenderViewHost 76 // to use for the next navigation, but before the navigation starts. 77 virtual void AboutToNavigateRenderView( 78 RenderViewHost* render_view_host) {} 79 80 // This method is invoked right after the navigation was initiated. 81 virtual void NavigateToPendingEntry( 82 const GURL& url, 83 NavigationController::ReloadType reload_type) {} 84 85 // |render_view_host| is the RenderViewHost for which the provisional load is 86 // happening. |frame_id| is a positive, non-zero integer identifying the 87 // navigating frame in the given |render_view_host|. |parent_frame_id| is the 88 // frame identifier of the frame containing the navigating frame, or -1 if the 89 // frame is not contained in another frame. 90 // 91 // Since the URL validation will strip error URLs, or srcdoc URLs, the boolean 92 // flags |is_error_page| and |is_iframe_srcdoc| will indicate that the not 93 // validated URL was either an error page or an iframe srcdoc. 94 // 95 // Note that during a cross-process navigation, several provisional loads 96 // can be on-going in parallel. 97 virtual void DidStartProvisionalLoadForFrame( 98 int64 frame_id, 99 int64 parent_frame_id, 100 bool is_main_frame, 101 const GURL& validated_url, 102 bool is_error_page, 103 bool is_iframe_srcdoc, 104 RenderViewHost* render_view_host) {} 105 106 // This method is invoked right after the DidStartProvisionalLoadForFrame if 107 // the provisional load affects the main frame, or if the provisional load 108 // was redirected. The latter use case is DEPRECATED. You should listen to 109 // WebContentsObserver::DidGetRedirectForResourceRequest instead. 110 virtual void ProvisionalChangeToMainFrameUrl( 111 const GURL& url, 112 RenderViewHost* render_view_host) {} 113 114 // This method is invoked when the provisional load was successfully 115 // committed. The |render_view_host| is now the current RenderViewHost of the 116 // WebContents. 117 // 118 // If the navigation only changed the reference fragment, or was triggered 119 // using the history API (e.g. window.history.replaceState), we will receive 120 // this signal without a prior DidStartProvisionalLoadForFrame signal. 121 virtual void DidCommitProvisionalLoadForFrame( 122 int64 frame_id, 123 bool is_main_frame, 124 const GURL& url, 125 PageTransition transition_type, 126 RenderViewHost* render_view_host) {} 127 128 // This method is invoked when the provisional load failed. 129 virtual void DidFailProvisionalLoad(int64 frame_id, 130 bool is_main_frame, 131 const GURL& validated_url, 132 int error_code, 133 const string16& error_description, 134 RenderViewHost* render_view_host) {} 135 136 // If the provisional load corresponded to the main frame, this method is 137 // invoked in addition to DidCommitProvisionalLoadForFrame. 138 virtual void DidNavigateMainFrame( 139 const LoadCommittedDetails& details, 140 const FrameNavigateParams& params) {} 141 142 // And regardless of what frame navigated, this method is invoked after 143 // DidCommitProvisionalLoadForFrame was invoked. 144 virtual void DidNavigateAnyFrame( 145 const LoadCommittedDetails& details, 146 const FrameNavigateParams& params) {} 147 148 // This method is invoked once the window.document object was created. 149 virtual void DocumentAvailableInMainFrame() {} 150 151 // This method is invoked when the document in the given frame finished 152 // loading. At this point, scripts marked as defer were executed, and 153 // content scripts marked "document_end" get injected into the frame. 154 virtual void DocumentLoadedInFrame(int64 frame_id, 155 RenderViewHost* render_view_host) {} 156 157 // This method is invoked when the navigation is done, i.e. the spinner of 158 // the tab will stop spinning, and the onload event was dispatched. 159 // 160 // If the WebContents is displaying replacement content, e.g. network error 161 // pages, DidFinishLoad is invoked for frames that were not sending 162 // navigational events before. It is safe to ignore these events. 163 virtual void DidFinishLoad(int64 frame_id, 164 const GURL& validated_url, 165 bool is_main_frame, 166 RenderViewHost* render_view_host) {} 167 168 // This method is like DidFinishLoad, but when the load failed or was 169 // cancelled, e.g. window.stop() is invoked. 170 virtual void DidFailLoad(int64 frame_id, 171 const GURL& validated_url, 172 bool is_main_frame, 173 int error_code, 174 const string16& error_description, 175 RenderViewHost* render_view_host) {} 176 177 // This method is invoked when content was loaded from an in-memory cache. 178 virtual void DidLoadResourceFromMemoryCache( 179 const LoadFromMemoryCacheDetails& details) {} 180 181 // This method is invoked when a response has been received for a resource 182 // request. 183 virtual void DidGetResourceResponseStart( 184 const ResourceRequestDetails& details) {} 185 186 // This method is invoked when a redirect was received while requesting a 187 // resource. 188 virtual void DidGetRedirectForResourceRequest( 189 const ResourceRedirectDetails& details) {} 190 191 // This method is invoked when a new non-pending navigation entry is created. 192 // This corresponds to one NavigationController entry being created 193 // (in the case of new navigations) or renavigated to (for back/forward 194 // navigations). 195 virtual void NavigationEntryCommitted( 196 const LoadCommittedDetails& load_details) {} 197 198 // This method is invoked when a new WebContents was created in response to 199 // an action in the observed WebContents, e.g. a link with target=_blank was 200 // clicked. The |source_frame_id| indicates in which frame the action took 201 // place. 202 virtual void DidOpenRequestedURL(WebContents* new_contents, 203 const GURL& url, 204 const Referrer& referrer, 205 WindowOpenDisposition disposition, 206 PageTransition transition, 207 int64 source_frame_id) {} 208 209 virtual void FrameDetached(RenderViewHost* render_view_host, 210 int64 frame_id) {} 211 212 // These two methods correspond to the points in time when the spinner of the 213 // tab starts and stops spinning. 214 virtual void DidStartLoading(RenderViewHost* render_view_host) {} 215 virtual void DidStopLoading(RenderViewHost* render_view_host) {} 216 217 // When WebContents::Stop() is called, the WebContents stops loading and then 218 // invokes this method. If there are ongoing navigations, their respective 219 // failure methods will also be invoked. 220 virtual void NavigationStopped() {} 221 222 // This indicates that the next navigation was triggered by a user gesture. 223 virtual void DidGetUserGesture() {} 224 225 // This method is invoked when a RenderViewHost of this WebContents was 226 // configured to ignore UI events, and an UI event took place. 227 virtual void DidGetIgnoredUIEvent() {} 228 229 // This method is invoked every time the WebContents becomes visible. 230 virtual void WasShown() {} 231 232 virtual void AppCacheAccessed(const GURL& manifest_url, 233 bool blocked_by_policy) {} 234 235 // Notification that a plugin has crashed. 236 // |plugin_pid| is the process ID identifying the plugin process. Note that 237 // this ID is supplied by the renderer, so should not be trusted. Besides, the 238 // corresponding process has probably died at this point. The ID may even have 239 // been reused by a new process. 240 virtual void PluginCrashed(const base::FilePath& plugin_path, 241 base::ProcessId plugin_pid) {} 242 243 // Notification that the given plugin has hung or become unhung. This 244 // notification is only for Pepper plugins. 245 // 246 // The plugin_child_id is the unique child process ID from the plugin. Note 247 // that this ID is supplied by the renderer, so should be validated before 248 // it's used for anything in case there's an exploited renderer. 249 virtual void PluginHungStatusChanged(int plugin_child_id, 250 const base::FilePath& plugin_path, 251 bool is_hung) {} 252 253 // Invoked when WebContents::Clone() was used to clone a WebContents. 254 virtual void DidCloneToNewWebContents(WebContents* old_web_contents, 255 WebContents* new_web_contents) {} 256 257 // Invoked when the WebContents is being destroyed. Gives subclasses a chance 258 // to cleanup. At the time this is invoked |web_contents()| returns NULL. 259 // It is safe to delete 'this' from here. 260 virtual void WebContentsDestroyed(WebContents* web_contents) {} 261 262 // Called when the user agent override for a WebContents has been changed. 263 virtual void UserAgentOverrideSet(const std::string& user_agent) {} 264 265 // Invoked when new FaviconURL candidates are received from the renderer. 266 virtual void DidUpdateFaviconURL(int32 page_id, 267 const std::vector<FaviconURL>& candidates) {} 268 269 // Invoked when a pepper plugin creates and shows or destroys a fullscreen 270 // render widget. 271 virtual void DidShowFullscreenWidget(int routing_id) {} 272 virtual void DidDestroyFullscreenWidget(int routing_id) {} 273 274 // Invoked when visible SSL state (as defined by SSLStatus) changes. 275 virtual void DidChangeVisibleSSLState() {} 276 277 // Invoked when an interstitial page is attached or detached. 278 virtual void DidAttachInterstitialPage() {} 279 virtual void DidDetachInterstitialPage() {} 280 281 // Invoked before a form repost warning is shown. 282 virtual void BeforeFormRepostWarningShow() {} 283 284 // Invoked when the beforeunload handler fires. The time is from the renderer. 285 virtual void BeforeUnloadFired(const base::TimeTicks& proceed_time) {} 286 287 // Invoked when a user cancels a before unload dialog. 288 virtual void BeforeUnloadDialogCancelled() {} 289 290 // IPC::Listener implementation. 291 virtual bool OnMessageReceived(const IPC::Message& message) OVERRIDE; 292 293 // IPC::Sender implementation. 294 virtual bool Send(IPC::Message* message) OVERRIDE; 295 int routing_id() const; 296 297 protected: 298 // Use this constructor when the object is tied to a single WebContents for 299 // its entire lifetime. 300 explicit WebContentsObserver(WebContents* web_contents); 301 302 // Use this constructor when the object wants to observe a WebContents for 303 // part of its lifetime. It can then call Observe() to start and stop 304 // observing. 305 WebContentsObserver(); 306 307 virtual ~WebContentsObserver(); 308 309 // Start observing a different WebContents; used with the default constructor. 310 void Observe(WebContents* web_contents); 311 312 WebContents* web_contents() const; 313 314 private: 315 friend class WebContentsImpl; 316 317 // Invoked from WebContentsImpl. Invokes WebContentsDestroyed and NULL out 318 // |web_contents_|. 319 void WebContentsImplDestroyed(); 320 321 WebContentsImpl* web_contents_; 322 323 DISALLOW_COPY_AND_ASSIGN(WebContentsObserver); 324}; 325 326} // namespace content 327 328#endif // CONTENT_PUBLIC_BROWSER_WEB_CONTENTS_OBSERVER_H_ 329