web_contents.h revision 5d1f7b1de12d16ceb2c938c56701a3e8bfa558f7
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_H_ 6#define CONTENT_PUBLIC_BROWSER_WEB_CONTENTS_H_ 7 8#include <set> 9 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" 27 28#if defined(OS_ANDROID) 29#include "base/android/scoped_java_ref.h" 30#endif 31 32namespace base { 33class TimeTicks; 34} 35 36namespace blink { 37struct WebFindOptions; 38} 39 40namespace gfx { 41class Rect; 42class Size; 43} 44 45namespace net { 46struct LoadStateWithParam; 47} 48 49namespace content { 50 51class BrowserContext; 52class InterstitialPage; 53class PageState; 54class RenderFrameHost; 55class RenderProcessHost; 56class RenderViewHost; 57class RenderWidgetHostView; 58class SiteInstance; 59class WebContentsDelegate; 60class WebContentsView; 61struct RendererPreferences; 62 63// WebContents is the core class in content/. A WebContents renders web content 64// (usually HTML) in a rectangular area. 65// 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. 73// 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 . 77// 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 82// for more details. 83class WebContents : public PageNavigator, 84 public IPC::Sender, 85 public base::SupportsUserData { 86 public: 87 struct CONTENT_EXPORT CreateParams { 88 explicit CreateParams(BrowserContext* context); 89 CreateParams(BrowserContext* context, SiteInstance* site); 90 91 BrowserContext* browser_context; 92 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; 97 98 WebContents* opener; 99 int routing_id; 100 int main_frame_routing_id; 101 102 // Initial size of the new WebContent's view. Can be (0, 0) if not needed. 103 gfx::Size initial_size; 104 105 // True if the contents should be initially hidden. 106 bool initially_hidden; 107 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; 111 }; 112 113 // Creates a new WebContents. 114 CONTENT_EXPORT static WebContents* Create(const CreateParams& params); 115 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). 121 // 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); 129 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); 134 135 CONTENT_EXPORT static WebContents* FromRenderFrameHost(RenderFrameHost* rfh); 136 137 virtual ~WebContents() {} 138 139 // Intrinsic tab state ------------------------------------------------------- 140 141 // Gets/Sets the delegate. 142 virtual WebContentsDelegate* GetDelegate() = 0; 143 virtual void SetDelegate(WebContentsDelegate* delegate) = 0; 144 145 // Gets the controller for this WebContents. 146 virtual NavigationController& GetController() = 0; 147 virtual const NavigationController& GetController() const = 0; 148 149 // Returns the user browser context associated with this WebContents (via the 150 // NavigationController). 151 virtual content::BrowserContext* GetBrowserContext() const = 0; 152 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; 157 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; 164 165 // Gets the last committed URL. It represents the current page that is 166 // displayed in this WebContents. It represents the current security 167 // context. 168 virtual const GURL& GetLastCommittedURL() const = 0; 169 170 // Return the currently active RenderProcessHost and RenderViewHost. Each of 171 // these may change over time. 172 virtual RenderProcessHost* GetRenderProcessHost() const = 0; 173 174 // Returns the main frame for the currently active view. 175 virtual RenderFrameHost* GetMainFrame() = 0; 176 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; 180 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; 184 185 // Gets the current RenderViewHost for this tab. 186 virtual RenderViewHost* GetRenderViewHost() const = 0; 187 188 typedef base::Callback<void(RenderViewHost* /* render_view_host */, 189 int /* x */, 190 int /* y */)> GetRenderViewHostCallback; 191 // Gets the RenderViewHost at coordinates (|x|, |y|) for this WebContents via 192 // |callback|. 193 // This can be different than the current RenderViewHost if there is a 194 // BrowserPlugin at the specified position. 195 virtual void GetRenderViewHostAtPosition( 196 int x, 197 int y, 198 const GetRenderViewHostCallback& callback) = 0; 199 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; 203 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; 208 209 // Gets the current RenderViewHost's routing id. Returns 210 // MSG_ROUTING_NONE when there is no RenderViewHost. 211 virtual int GetRoutingID() const = 0; 212 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; 216 217 // Returns the currently active fullscreen widget. If there is none, returns 218 // NULL. 219 virtual RenderWidgetHostView* GetFullscreenRenderWidgetHostView() const = 0; 220 221 // The WebContentsView will never change and is guaranteed non-NULL. 222 virtual WebContentsView* GetView() const = 0; 223 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; 229 230 // Returns the committed WebUI if one exists, otherwise the pending one. 231 virtual WebUI* GetWebUI() const = 0; 232 virtual WebUI* GetCommittedWebUI() const = 0; 233 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; 237 238#if defined(OS_WIN) 239 virtual void SetParentNativeViewAccessible( 240 gfx::NativeViewAccessible accessible_parent) = 0; 241#endif 242 243 // Tab navigation state ------------------------------------------------------ 244 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; 249 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; 255 256 // The max page ID for any page that the given SiteInstance has loaded in 257 // this WebContents. 258 virtual int32 GetMaxPageIDForSiteInstance(SiteInstance* site_instance) = 0; 259 260 // Returns the SiteInstance associated with the current page. 261 virtual SiteInstance* GetSiteInstance() const = 0; 262 263 // Returns the SiteInstance for the pending navigation, if any. Otherwise 264 // returns the current SiteInstance. 265 virtual SiteInstance* GetPendingSiteInstance() const = 0; 266 267 // Return whether this WebContents is loading a resource. 268 virtual bool IsLoading() const = 0; 269 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; 273 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; 277 278 // Return the upload progress. 279 virtual uint64 GetUploadSize() const = 0; 280 virtual uint64 GetUploadPosition() const = 0; 281 282 // Returns a set of the site URLs currently committed in this tab. 283 virtual std::set<GURL> GetSitesInTab() const = 0; 284 285 // Return the character encoding of the page. 286 virtual const std::string& GetEncoding() const = 0; 287 288 // True if this is a secure page which displayed insecure content. 289 virtual bool DisplayedInsecureContent() const = 0; 290 291 // Internal state ------------------------------------------------------------ 292 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. |capture_size| specifies the capturer's video 296 // resolution, but can be empty to mean "unspecified." The first screen 297 // capturer that provides a non-empty |capture_size| will override the value 298 // returned by GetPreferredSize() until all captures have ended. 299 virtual void IncrementCapturerCount(const gfx::Size& capture_size) = 0; 300 virtual void DecrementCapturerCount() = 0; 301 virtual int GetCapturerCount() const = 0; 302 303 // Indicates whether this tab should be considered crashed. The setter will 304 // also notify the delegate when the flag is changed. 305 virtual bool IsCrashed() const = 0; 306 virtual void SetIsCrashed(base::TerminationStatus status, int error_code) = 0; 307 308 virtual base::TerminationStatus GetCrashedStatus() const = 0; 309 310 // Whether the tab is in the process of being destroyed. 311 virtual bool IsBeingDestroyed() const = 0; 312 313 // Convenience method for notifying the delegate of a navigation state 314 // change. See InvalidateType enum. 315 virtual void NotifyNavigationStateChanged(unsigned changed_flags) = 0; 316 317 // Get the last time that the WebContents was made active (either when it was 318 // created or shown with WasShown()). 319 virtual base::TimeTicks GetLastActiveTime() const = 0; 320 321 // Invoked when the WebContents becomes shown/hidden. 322 virtual void WasShown() = 0; 323 virtual void WasHidden() = 0; 324 325 // Returns true if the before unload and unload listeners need to be 326 // fired. The value of this changes over time. For example, if true and the 327 // before unload listener is executed and allows the user to exit, then this 328 // returns false. 329 virtual bool NeedToFireBeforeUnload() = 0; 330 331 // Commands ------------------------------------------------------------------ 332 333 // Stop any pending navigation. 334 virtual void Stop() = 0; 335 336 // Creates a new WebContents with the same state as this one. The returned 337 // heap-allocated pointer is owned by the caller. 338 virtual WebContents* Clone() = 0; 339 340 // Views and focus ----------------------------------------------------------- 341 // Focuses the first (last if |reverse| is true) element in the page. 342 // Invoked when this tab is getting the focus through tab traversal (|reverse| 343 // is true when using Shift-Tab). 344 virtual void FocusThroughTabTraversal(bool reverse) = 0; 345 346 // Interstitials ------------------------------------------------------------- 347 348 // Various other systems need to know about our interstitials. 349 virtual bool ShowingInterstitialPage() const = 0; 350 351 // Returns the currently showing interstitial, NULL if no interstitial is 352 // showing. 353 virtual InterstitialPage* GetInterstitialPage() const = 0; 354 355 // Misc state & callbacks ---------------------------------------------------- 356 357 // Check whether we can do the saving page operation this page given its MIME 358 // type. 359 virtual bool IsSavable() = 0; 360 361 // Prepare for saving the current web page to disk. 362 virtual void OnSavePage() = 0; 363 364 // Save page with the main HTML file path, the directory for saving resources, 365 // and the save type: HTML only or complete web page. Returns true if the 366 // saving process has been initiated successfully. 367 virtual bool SavePage(const base::FilePath& main_file, 368 const base::FilePath& dir_path, 369 SavePageType save_type) = 0; 370 371 // Saves the given frame's URL to the local filesystem.. 372 virtual void SaveFrame(const GURL& url, 373 const Referrer& referrer) = 0; 374 375 // Generate an MHTML representation of the current page in the given file. 376 virtual void GenerateMHTML( 377 const base::FilePath& file, 378 const base::Callback<void( 379 int64 /* size of the file */)>& callback) = 0; 380 381 // Returns true if the active NavigationEntry's page_id equals page_id. 382 virtual bool IsActiveEntry(int32 page_id) = 0; 383 384 // Returns the contents MIME type after a navigation. 385 virtual const std::string& GetContentsMimeType() const = 0; 386 387 // Returns true if this WebContents will notify about disconnection. 388 virtual bool WillNotifyDisconnection() const = 0; 389 390 // Override the encoding and reload the page by sending down 391 // ViewMsg_SetPageEncoding to the renderer. |UpdateEncoding| is kinda 392 // the opposite of this, by which 'browser' is notified of 393 // the encoding of the current tab from 'renderer' (determined by 394 // auto-detect, http header, meta, bom detection, etc). 395 virtual void SetOverrideEncoding(const std::string& encoding) = 0; 396 397 // Remove any user-defined override encoding and reload by sending down 398 // ViewMsg_ResetPageEncodingToDefault to the renderer. 399 virtual void ResetOverrideEncoding() = 0; 400 401 // Returns the settings which get passed to the renderer. 402 virtual content::RendererPreferences* GetMutableRendererPrefs() = 0; 403 404 // Tells the tab to close now. The tab will take care not to close until it's 405 // out of nested message loops. 406 virtual void Close() = 0; 407 408 // A render view-originated drag has ended. Informs the render view host and 409 // WebContentsDelegate. 410 virtual void SystemDragEnded() = 0; 411 412 // Notification the user has made a gesture while focus was on the 413 // page. This is used to avoid uninitiated user downloads (aka carpet 414 // bombing), see DownloadRequestLimiter for details. 415 virtual void UserGestureDone() = 0; 416 417 // Indicates if this tab was explicitly closed by the user (control-w, close 418 // tab menu item...). This is false for actions that indirectly close the tab, 419 // such as closing the window. The setter is maintained by TabStripModel, and 420 // the getter only useful from within TAB_CLOSED notification 421 virtual void SetClosedByUserGesture(bool value) = 0; 422 virtual bool GetClosedByUserGesture() const = 0; 423 424 // Gets the zoom level for this tab. 425 virtual double GetZoomLevel() const = 0; 426 427 // Gets the zoom percent for this tab. 428 virtual int GetZoomPercent(bool* enable_increment, 429 bool* enable_decrement) const = 0; 430 431 // Opens view-source tab for this contents. 432 virtual void ViewSource() = 0; 433 434 virtual void ViewFrameSource(const GURL& url, 435 const PageState& page_state)= 0; 436 437 // Gets the minimum/maximum zoom percent. 438 virtual int GetMinimumZoomPercent() const = 0; 439 virtual int GetMaximumZoomPercent() const = 0; 440 441 // Gets the preferred size of the contents. 442 virtual gfx::Size GetPreferredSize() const = 0; 443 444 // Called when the reponse to a pending mouse lock request has arrived. 445 // Returns true if |allowed| is true and the mouse has been successfully 446 // locked. 447 virtual bool GotResponseToLockMouseRequest(bool allowed) = 0; 448 449 // Called when the user has selected a color in the color chooser. 450 virtual void DidChooseColorInColorChooser(SkColor color) = 0; 451 452 // Called when the color chooser has ended. 453 virtual void DidEndColorChooser() = 0; 454 455 // Returns true if the location bar should be focused by default rather than 456 // the page contents. The view calls this function when the tab is focused 457 // to see what it should do. 458 virtual bool FocusLocationBarByDefault() = 0; 459 460 // Does this have an opener associated with it? 461 virtual bool HasOpener() const = 0; 462 463 typedef base::Callback<void( 464 int, /* id */ 465 int, /* HTTP status code */ 466 const GURL&, /* image_url */ 467 const std::vector<SkBitmap>&, /* bitmaps */ 468 /* The sizes in pixel of the bitmaps before they were resized due to the 469 max bitmap size passed to DownloadImage(). Each entry in the bitmaps 470 vector corresponds to an entry in the sizes vector. If a bitmap was 471 resized, there should be a single returned bitmap. */ 472 const std::vector<gfx::Size>&)> 473 ImageDownloadCallback; 474 475 // Sends a request to download the given image |url| and returns the unique 476 // id of the download request. When the download is finished, |callback| will 477 // be called with the bitmaps received from the renderer. If |is_favicon| is 478 // true, the cookies are not sent and not accepted during download. 479 // Bitmaps with pixel sizes larger than |max_bitmap_size| are filtered out 480 // from the bitmap results. If there are no bitmap results <= 481 // |max_bitmap_size|, the smallest bitmap is resized to |max_bitmap_size| and 482 // is the only result. A |max_bitmap_size| of 0 means unlimited. 483 virtual int DownloadImage(const GURL& url, 484 bool is_favicon, 485 uint32_t max_bitmap_size, 486 const ImageDownloadCallback& callback) = 0; 487 488 // Returns true if the WebContents is responsible for displaying a subframe 489 // in a different process from its parent page. 490 // TODO: this doesn't really belong here. With site isolation, this should be 491 // removed since we can then embed iframes in different processes. 492 virtual bool IsSubframe() const = 0; 493 494 // Sets the zoom level for the current page and all BrowserPluginGuests 495 // within the page. 496 virtual void SetZoomLevel(double level) = 0; 497 498 // Finds text on a page. 499 virtual void Find(int request_id, 500 const base::string16& search_text, 501 const blink::WebFindOptions& options) = 0; 502 503 // Notifies the renderer that the user has closed the FindInPage window 504 // (and what action to take regarding the selection). 505 virtual void StopFinding(StopFindAction action) = 0; 506 507#if defined(OS_ANDROID) 508 CONTENT_EXPORT static WebContents* FromJavaWebContents( 509 jobject jweb_contents_android); 510 virtual base::android::ScopedJavaLocalRef<jobject> GetJavaWebContents() = 0; 511#endif // OS_ANDROID 512 513 private: 514 // This interface should only be implemented inside content. 515 friend class WebContentsImpl; 516 WebContents() {} 517}; 518 519} // namespace content 520 521#endif // CONTENT_PUBLIC_BROWSER_WEB_CONTENTS_H_ 522