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_H_
6 #define CONTENT_PUBLIC_BROWSER_WEB_CONTENTS_H_
10 #include "base/basictypes.h"
11 #include "base/callback_forward.h"
12 #include "base/files/file_path.h"
13 #include "base/process/kill.h"
14 #include "base/strings/string16.h"
15 #include "base/supports_user_data.h"
16 #include "content/common/content_export.h"
17 #include "content/public/browser/navigation_controller.h"
18 #include "content/public/browser/page_navigator.h"
19 #include "content/public/browser/save_page_type.h"
20 #include "content/public/browser/web_ui.h"
21 #include "content/public/common/stop_find_action.h"
22 #include "ipc/ipc_sender.h"
23 #include "third_party/skia/include/core/SkColor.h"
24 #include "ui/base/window_open_disposition.h"
25 #include "ui/gfx/native_widget_types.h"
26 #include "ui/gfx/size.h"
28 #if defined(OS_ANDROID)
29 #include "base/android/scoped_java_ref.h"
37 struct WebFindOptions;
46 struct LoadStateWithParam;
52 class InterstitialPage;
54 class RenderFrameHost;
55 class RenderProcessHost;
57 class RenderWidgetHostView;
59 class WebContentsDelegate;
60 class WebContentsView;
61 struct RendererPreferences;
63 // WebContents is the core class in content/. A WebContents renders web content
64 // (usually HTML) in a rectangular area.
66 // Instantiating one is simple:
67 // scoped_ptr<content::WebContents> web_contents(
68 // content::WebContents::Create(
69 // content::WebContents::CreateParams(browser_context)));
70 // gfx::NativeView view = web_contents->GetView()->GetNativeView();
71 // // |view| is an HWND, NSView*, GtkWidget*, etc.; insert it into the view
72 // // hierarchy wherever it needs to go.
74 // That's it; go to your kitchen, grab a scone, and chill. WebContents will do
75 // all the multi-process stuff behind the scenes. More details are at
76 // http://www.chromium.org/developers/design-documents/multi-process-architecture .
78 // Each WebContents has exactly one NavigationController; each
79 // NavigationController belongs to one WebContents. The NavigationController can
80 // be obtained from GetController(), and is used to load URLs into the
81 // WebContents, navigate it backwards/forwards, etc. See navigation_controller.h
83 class WebContents : public PageNavigator,
85 public base::SupportsUserData {
87 struct CONTENT_EXPORT CreateParams {
88 explicit CreateParams(BrowserContext* context);
89 CreateParams(BrowserContext* context, SiteInstance* site);
91 BrowserContext* browser_context;
93 // Specifying a SiteInstance here is optional. It can be set to avoid an
94 // extra process swap if the first navigation is expected to require a
95 // privileged process.
96 SiteInstance* site_instance;
100 int main_frame_routing_id;
102 // Initial size of the new WebContent's view. Can be (0, 0) if not needed.
103 gfx::Size initial_size;
105 // True if the contents should be initially hidden.
106 bool initially_hidden;
108 // Used to specify the location context which display the new view should
109 // belong. This can be NULL if not needed.
110 gfx::NativeView context;
113 // Creates a new WebContents.
114 CONTENT_EXPORT static WebContents* Create(const CreateParams& params);
116 // Similar to Create() above but should be used when you need to prepopulate
117 // the SessionStorageNamespaceMap of the WebContents. This can happen if
118 // you duplicate a WebContents, try to reconstitute it from a saved state,
119 // or when you create a new WebContents based on another one (eg., when
120 // servicing a window.open() call).
122 // You do not want to call this. If you think you do, make sure you completely
123 // understand when SessionStorageNamespace objects should be cloned, why
124 // they should not be shared by multiple WebContents, and what bad things
125 // can happen if you share the object.
126 CONTENT_EXPORT static WebContents* CreateWithSessionStorage(
127 const CreateParams& params,
128 const SessionStorageNamespaceMap& session_storage_namespace_map);
130 // Returns a WebContents that wraps the RenderViewHost, or NULL if the
131 // render view host's delegate isn't a WebContents.
132 CONTENT_EXPORT static WebContents* FromRenderViewHost(
133 const RenderViewHost* rvh);
135 CONTENT_EXPORT static WebContents* FromRenderFrameHost(RenderFrameHost* rfh);
137 virtual ~WebContents() {}
139 // Intrinsic tab state -------------------------------------------------------
141 // Gets/Sets the delegate.
142 virtual WebContentsDelegate* GetDelegate() = 0;
143 virtual void SetDelegate(WebContentsDelegate* delegate) = 0;
145 // Gets the controller for this WebContents.
146 virtual NavigationController& GetController() = 0;
147 virtual const NavigationController& GetController() const = 0;
149 // Returns the user browser context associated with this WebContents (via the
150 // NavigationController).
151 virtual content::BrowserContext* GetBrowserContext() const = 0;
153 // Gets the URL that is currently being displayed, if there is one.
154 // This method is deprecated. DO NOT USE! Pick either |GetVisibleURL| or
155 // |GetLastCommittedURL| as appropriate.
156 virtual const GURL& GetURL() const = 0;
158 // Gets the URL currently being displayed in the URL bar, if there is one.
159 // This URL might be a pending navigation that hasn't committed yet, so it is
160 // not guaranteed to match the current page in this WebContents. A typical
161 // example of this is interstitials, which show the URL of the new/loading
162 // page (active) but the security context is of the old page (last committed).
163 virtual const GURL& GetVisibleURL() const = 0;
165 // Gets the last committed URL. It represents the current page that is
166 // displayed in this WebContents. It represents the current security
168 virtual const GURL& GetLastCommittedURL() const = 0;
170 // Return the currently active RenderProcessHost and RenderViewHost. Each of
171 // these may change over time.
172 virtual RenderProcessHost* GetRenderProcessHost() const = 0;
174 // Returns the main frame for the currently active view.
175 virtual RenderFrameHost* GetMainFrame() = 0;
177 // Calls |on_frame| for each frame in the currently active view.
178 virtual void ForEachFrame(
179 const base::Callback<void(RenderFrameHost*)>& on_frame) = 0;
181 // Sends the given IPC to all frames in the currently active view. This is a
182 // convenience method instead of calling ForEach.
183 virtual void SendToAllFrames(IPC::Message* message) = 0;
185 // Gets the current RenderViewHost for this tab.
186 virtual RenderViewHost* GetRenderViewHost() const = 0;
188 typedef base::Callback<void(RenderViewHost* /* render_view_host */,
190 int /* y */)> GetRenderViewHostCallback;
191 // Gets the RenderViewHost at coordinates (|x|, |y|) for this WebContents via
193 // This can be different than the current RenderViewHost if there is a
194 // BrowserPlugin at the specified position.
195 virtual void GetRenderViewHostAtPosition(
198 const GetRenderViewHostCallback& callback) = 0;
200 // Returns the WebContents embedding this WebContents, if any.
201 // If this is a top-level WebContents then it returns NULL.
202 virtual WebContents* GetEmbedderWebContents() const = 0;
204 // Gets the instance ID of the current WebContents if it is embedded
205 // within a BrowserPlugin. The instance ID of a WebContents uniquely
206 // identifies it within its embedder WebContents.
207 virtual int GetEmbeddedInstanceID() const = 0;
209 // Gets the current RenderViewHost's routing id. Returns
210 // MSG_ROUTING_NONE when there is no RenderViewHost.
211 virtual int GetRoutingID() const = 0;
213 // Returns the currently active RenderWidgetHostView. This may change over
214 // time and can be NULL (during setup and teardown).
215 virtual RenderWidgetHostView* GetRenderWidgetHostView() const = 0;
217 // Returns the currently active fullscreen widget. If there is none, returns
219 virtual RenderWidgetHostView* GetFullscreenRenderWidgetHostView() const = 0;
221 // The WebContentsView will never change and is guaranteed non-NULL.
222 virtual WebContentsView* GetView() const = 0;
224 // Create a WebUI page for the given url. In most cases, this doesn't need to
225 // be called by embedders since content will create its own WebUI objects as
226 // necessary. However if the embedder wants to create its own WebUI object and
227 // keep track of it manually, it can use this.
228 virtual WebUI* CreateWebUI(const GURL& url) = 0;
230 // Returns the committed WebUI if one exists, otherwise the pending one.
231 virtual WebUI* GetWebUI() const = 0;
232 virtual WebUI* GetCommittedWebUI() const = 0;
234 // Allows overriding the user agent used for NavigationEntries it owns.
235 virtual void SetUserAgentOverride(const std::string& override) = 0;
236 virtual const std::string& GetUserAgentOverride() const = 0;
239 virtual void SetParentNativeViewAccessible(
240 gfx::NativeViewAccessible accessible_parent) = 0;
243 // Tab navigation state ------------------------------------------------------
245 // Returns the current navigation properties, which if a navigation is
246 // pending may be provisional (e.g., the navigation could result in a
247 // download, in which case the URL would revert to what it was previously).
248 virtual const base::string16& GetTitle() const = 0;
250 // The max page ID for any page that the current SiteInstance has loaded in
251 // this WebContents. Page IDs are specific to a given SiteInstance and
252 // WebContents, corresponding to a specific RenderView in the renderer.
253 // Page IDs increase with each new page that is loaded by a tab.
254 virtual int32 GetMaxPageID() = 0;
256 // The max page ID for any page that the given SiteInstance has loaded in
258 virtual int32 GetMaxPageIDForSiteInstance(SiteInstance* site_instance) = 0;
260 // Returns the SiteInstance associated with the current page.
261 virtual SiteInstance* GetSiteInstance() const = 0;
263 // Returns the SiteInstance for the pending navigation, if any. Otherwise
264 // returns the current SiteInstance.
265 virtual SiteInstance* GetPendingSiteInstance() const = 0;
267 // Return whether this WebContents is loading a resource.
268 virtual bool IsLoading() const = 0;
270 // Returns whether this WebContents is waiting for a first-response for the
271 // main resource of the page.
272 virtual bool IsWaitingForResponse() const = 0;
274 // Return the current load state and the URL associated with it.
275 virtual const net::LoadStateWithParam& GetLoadState() const = 0;
276 virtual const base::string16& GetLoadStateHost() const = 0;
278 // Return the upload progress.
279 virtual uint64 GetUploadSize() const = 0;
280 virtual uint64 GetUploadPosition() const = 0;
282 // Returns a set of the site URLs currently committed in this tab.
283 virtual std::set<GURL> GetSitesInTab() const = 0;
285 // Return the character encoding of the page.
286 virtual const std::string& GetEncoding() const = 0;
288 // True if this is a secure page which displayed insecure content.
289 virtual bool DisplayedInsecureContent() const = 0;
291 // Internal state ------------------------------------------------------------
293 // Indicates whether the WebContents is being captured (e.g., for screenshots
294 // or mirroring). Increment calls must be balanced with an equivalent number
295 // of decrement calls.
296 virtual void IncrementCapturerCount() = 0;
297 virtual void DecrementCapturerCount() = 0;
298 virtual int GetCapturerCount() const = 0;
300 // Indicates whether this tab should be considered crashed. The setter will
301 // also notify the delegate when the flag is changed.
302 virtual bool IsCrashed() const = 0;
303 virtual void SetIsCrashed(base::TerminationStatus status, int error_code) = 0;
305 virtual base::TerminationStatus GetCrashedStatus() const = 0;
307 // Whether the tab is in the process of being destroyed.
308 virtual bool IsBeingDestroyed() const = 0;
310 // Convenience method for notifying the delegate of a navigation state
311 // change. See InvalidateType enum.
312 virtual void NotifyNavigationStateChanged(unsigned changed_flags) = 0;
314 // Get the last time that the WebContents was made visible with WasShown()
315 virtual base::TimeTicks GetLastSelectedTime() const = 0;
317 // Invoked when the WebContents becomes shown/hidden.
318 virtual void WasShown() = 0;
319 virtual void WasHidden() = 0;
321 // Returns true if the before unload and unload listeners need to be
322 // fired. The value of this changes over time. For example, if true and the
323 // before unload listener is executed and allows the user to exit, then this
325 virtual bool NeedToFireBeforeUnload() = 0;
327 // Commands ------------------------------------------------------------------
329 // Stop any pending navigation.
330 virtual void Stop() = 0;
332 // Creates a new WebContents with the same state as this one. The returned
333 // heap-allocated pointer is owned by the caller.
334 virtual WebContents* Clone() = 0;
336 // Views and focus -----------------------------------------------------------
337 // Focuses the first (last if |reverse| is true) element in the page.
338 // Invoked when this tab is getting the focus through tab traversal (|reverse|
339 // is true when using Shift-Tab).
340 virtual void FocusThroughTabTraversal(bool reverse) = 0;
342 // Interstitials -------------------------------------------------------------
344 // Various other systems need to know about our interstitials.
345 virtual bool ShowingInterstitialPage() const = 0;
347 // Returns the currently showing interstitial, NULL if no interstitial is
349 virtual InterstitialPage* GetInterstitialPage() const = 0;
351 // Misc state & callbacks ----------------------------------------------------
353 // Check whether we can do the saving page operation this page given its MIME
355 virtual bool IsSavable() = 0;
357 // Prepare for saving the current web page to disk.
358 virtual void OnSavePage() = 0;
360 // Save page with the main HTML file path, the directory for saving resources,
361 // and the save type: HTML only or complete web page. Returns true if the
362 // saving process has been initiated successfully.
363 virtual bool SavePage(const base::FilePath& main_file,
364 const base::FilePath& dir_path,
365 SavePageType save_type) = 0;
367 // Saves the given frame's URL to the local filesystem..
368 virtual void SaveFrame(const GURL& url,
369 const Referrer& referrer) = 0;
371 // Generate an MHTML representation of the current page in the given file.
372 virtual void GenerateMHTML(
373 const base::FilePath& file,
374 const base::Callback<void(
375 int64 /* size of the file */)>& callback) = 0;
377 // Returns true if the active NavigationEntry's page_id equals page_id.
378 virtual bool IsActiveEntry(int32 page_id) = 0;
380 // Returns the contents MIME type after a navigation.
381 virtual const std::string& GetContentsMimeType() const = 0;
383 // Returns true if this WebContents will notify about disconnection.
384 virtual bool WillNotifyDisconnection() const = 0;
386 // Override the encoding and reload the page by sending down
387 // ViewMsg_SetPageEncoding to the renderer. |UpdateEncoding| is kinda
388 // the opposite of this, by which 'browser' is notified of
389 // the encoding of the current tab from 'renderer' (determined by
390 // auto-detect, http header, meta, bom detection, etc).
391 virtual void SetOverrideEncoding(const std::string& encoding) = 0;
393 // Remove any user-defined override encoding and reload by sending down
394 // ViewMsg_ResetPageEncodingToDefault to the renderer.
395 virtual void ResetOverrideEncoding() = 0;
397 // Returns the settings which get passed to the renderer.
398 virtual content::RendererPreferences* GetMutableRendererPrefs() = 0;
400 // Tells the tab to close now. The tab will take care not to close until it's
401 // out of nested message loops.
402 virtual void Close() = 0;
404 // A render view-originated drag has ended. Informs the render view host and
405 // WebContentsDelegate.
406 virtual void SystemDragEnded() = 0;
408 // Notification the user has made a gesture while focus was on the
409 // page. This is used to avoid uninitiated user downloads (aka carpet
410 // bombing), see DownloadRequestLimiter for details.
411 virtual void UserGestureDone() = 0;
413 // Indicates if this tab was explicitly closed by the user (control-w, close
414 // tab menu item...). This is false for actions that indirectly close the tab,
415 // such as closing the window. The setter is maintained by TabStripModel, and
416 // the getter only useful from within TAB_CLOSED notification
417 virtual void SetClosedByUserGesture(bool value) = 0;
418 virtual bool GetClosedByUserGesture() const = 0;
420 // Gets the zoom level for this tab.
421 virtual double GetZoomLevel() const = 0;
423 // Gets the zoom percent for this tab.
424 virtual int GetZoomPercent(bool* enable_increment,
425 bool* enable_decrement) const = 0;
427 // Opens view-source tab for this contents.
428 virtual void ViewSource() = 0;
430 virtual void ViewFrameSource(const GURL& url,
431 const PageState& page_state)= 0;
433 // Gets the minimum/maximum zoom percent.
434 virtual int GetMinimumZoomPercent() const = 0;
435 virtual int GetMaximumZoomPercent() const = 0;
437 // Gets the preferred size of the contents.
438 virtual gfx::Size GetPreferredSize() const = 0;
440 // Called when the reponse to a pending mouse lock request has arrived.
441 // Returns true if |allowed| is true and the mouse has been successfully
443 virtual bool GotResponseToLockMouseRequest(bool allowed) = 0;
445 // Called when the user has selected a color in the color chooser.
446 virtual void DidChooseColorInColorChooser(SkColor color) = 0;
448 // Called when the color chooser has ended.
449 virtual void DidEndColorChooser() = 0;
451 // Returns true if the location bar should be focused by default rather than
452 // the page contents. The view calls this function when the tab is focused
453 // to see what it should do.
454 virtual bool FocusLocationBarByDefault() = 0;
456 // Does this have an opener associated with it?
457 virtual bool HasOpener() const = 0;
459 typedef base::Callback<void(
461 int, /* HTTP status code */
462 const GURL&, /* image_url */
463 const std::vector<SkBitmap>&, /* bitmaps */
464 /* The sizes in pixel of the bitmaps before they were resized due to the
465 max bitmap size passed to DownloadImage(). Each entry in the bitmaps
466 vector corresponds to an entry in the sizes vector. If a bitmap was
467 resized, there should be a single returned bitmap. */
468 const std::vector<gfx::Size>&)>
469 ImageDownloadCallback;
471 // Sends a request to download the given image |url| and returns the unique
472 // id of the download request. When the download is finished, |callback| will
473 // be called with the bitmaps received from the renderer. If |is_favicon| is
474 // true, the cookies are not sent and not accepted during download.
475 // Bitmaps with pixel sizes larger than |max_bitmap_size| are filtered out
476 // from the bitmap results. If there are no bitmap results <=
477 // |max_bitmap_size|, the smallest bitmap is resized to |max_bitmap_size| and
478 // is the only result. A |max_bitmap_size| of 0 means unlimited.
479 virtual int DownloadImage(const GURL& url,
481 uint32_t max_bitmap_size,
482 const ImageDownloadCallback& callback) = 0;
484 // Returns true if the WebContents is responsible for displaying a subframe
485 // in a different process from its parent page.
486 // TODO: this doesn't really belong here. With site isolation, this should be
487 // removed since we can then embed iframes in different processes.
488 virtual bool IsSubframe() const = 0;
490 // Sets the zoom level for the current page and all BrowserPluginGuests
492 virtual void SetZoomLevel(double level) = 0;
494 // Finds text on a page.
495 virtual void Find(int request_id,
496 const base::string16& search_text,
497 const blink::WebFindOptions& options) = 0;
499 // Notifies the renderer that the user has closed the FindInPage window
500 // (and what action to take regarding the selection).
501 virtual void StopFinding(StopFindAction action) = 0;
503 #if defined(OS_ANDROID)
504 CONTENT_EXPORT static WebContents* FromJavaWebContents(
505 jobject jweb_contents_android);
506 virtual base::android::ScopedJavaLocalRef<jobject> GetJavaWebContents() = 0;
510 // This interface should only be implemented inside content.
511 friend class WebContentsImpl;
515 } // namespace content
517 #endif // CONTENT_PUBLIC_BROWSER_WEB_CONTENTS_H_