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