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