web_contents.h revision a1401311d1ab56c4ed0a474bd38c108f75cb0cd9
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 // Returns the focused frame for the currently active view. 178 virtual RenderFrameHost* GetFocusedFrame() = 0; 179 180 // Calls |on_frame| for each frame in the currently active view. 181 virtual void ForEachFrame( 182 const base::Callback<void(RenderFrameHost*)>& on_frame) = 0; 183 184 // Sends the given IPC to all frames in the currently active view. This is a 185 // convenience method instead of calling ForEach. 186 virtual void SendToAllFrames(IPC::Message* message) = 0; 187 188 // Gets the current RenderViewHost for this tab. 189 virtual RenderViewHost* GetRenderViewHost() const = 0; 190 191 // Returns the WebContents embedding this WebContents, if any. 192 // If this is a top-level WebContents then it returns NULL. 193 virtual WebContents* GetEmbedderWebContents() const = 0; 194 195 // Gets the instance ID of the current WebContents if it is embedded 196 // within a BrowserPlugin. The instance ID of a WebContents uniquely 197 // identifies it within its embedder WebContents. 198 virtual int GetEmbeddedInstanceID() const = 0; 199 200 // Gets the current RenderViewHost's routing id. Returns 201 // MSG_ROUTING_NONE when there is no RenderViewHost. 202 virtual int GetRoutingID() const = 0; 203 204 // Returns the currently active RenderWidgetHostView. This may change over 205 // time and can be NULL (during setup and teardown). 206 virtual RenderWidgetHostView* GetRenderWidgetHostView() const = 0; 207 208 // Returns the currently active fullscreen widget. If there is none, returns 209 // NULL. 210 virtual RenderWidgetHostView* GetFullscreenRenderWidgetHostView() const = 0; 211 212 // The WebContentsView will never change and is guaranteed non-NULL. 213 virtual WebContentsView* GetView() const = 0; 214 215 // Create a WebUI page for the given url. In most cases, this doesn't need to 216 // be called by embedders since content will create its own WebUI objects as 217 // necessary. However if the embedder wants to create its own WebUI object and 218 // keep track of it manually, it can use this. 219 virtual WebUI* CreateWebUI(const GURL& url) = 0; 220 221 // Returns the committed WebUI if one exists, otherwise the pending one. 222 virtual WebUI* GetWebUI() const = 0; 223 virtual WebUI* GetCommittedWebUI() const = 0; 224 225 // Allows overriding the user agent used for NavigationEntries it owns. 226 virtual void SetUserAgentOverride(const std::string& override) = 0; 227 virtual const std::string& GetUserAgentOverride() const = 0; 228 229#if defined(OS_WIN) 230 virtual void SetParentNativeViewAccessible( 231 gfx::NativeViewAccessible accessible_parent) = 0; 232#endif 233 234 // Tab navigation state ------------------------------------------------------ 235 236 // Returns the current navigation properties, which if a navigation is 237 // pending may be provisional (e.g., the navigation could result in a 238 // download, in which case the URL would revert to what it was previously). 239 virtual const base::string16& GetTitle() const = 0; 240 241 // The max page ID for any page that the current SiteInstance has loaded in 242 // this WebContents. Page IDs are specific to a given SiteInstance and 243 // WebContents, corresponding to a specific RenderView in the renderer. 244 // Page IDs increase with each new page that is loaded by a tab. 245 virtual int32 GetMaxPageID() = 0; 246 247 // The max page ID for any page that the given SiteInstance has loaded in 248 // this WebContents. 249 virtual int32 GetMaxPageIDForSiteInstance(SiteInstance* site_instance) = 0; 250 251 // Returns the SiteInstance associated with the current page. 252 virtual SiteInstance* GetSiteInstance() const = 0; 253 254 // Returns the SiteInstance for the pending navigation, if any. Otherwise 255 // returns the current SiteInstance. 256 virtual SiteInstance* GetPendingSiteInstance() const = 0; 257 258 // Return whether this WebContents is loading a resource. 259 virtual bool IsLoading() const = 0; 260 261 // Returns whether this WebContents is waiting for a first-response for the 262 // main resource of the page. 263 virtual bool IsWaitingForResponse() const = 0; 264 265 // Return the current load state and the URL associated with it. 266 virtual const net::LoadStateWithParam& GetLoadState() const = 0; 267 virtual const base::string16& GetLoadStateHost() const = 0; 268 269 // Return the upload progress. 270 virtual uint64 GetUploadSize() const = 0; 271 virtual uint64 GetUploadPosition() const = 0; 272 273 // Returns a set of the site URLs currently committed in this tab. 274 virtual std::set<GURL> GetSitesInTab() const = 0; 275 276 // Return the character encoding of the page. 277 virtual const std::string& GetEncoding() const = 0; 278 279 // True if this is a secure page which displayed insecure content. 280 virtual bool DisplayedInsecureContent() const = 0; 281 282 // Internal state ------------------------------------------------------------ 283 284 // Indicates whether the WebContents is being captured (e.g., for screenshots 285 // or mirroring). Increment calls must be balanced with an equivalent number 286 // of decrement calls. |capture_size| specifies the capturer's video 287 // resolution, but can be empty to mean "unspecified." The first screen 288 // capturer that provides a non-empty |capture_size| will override the value 289 // returned by GetPreferredSize() until all captures have ended. 290 virtual void IncrementCapturerCount(const gfx::Size& capture_size) = 0; 291 virtual void DecrementCapturerCount() = 0; 292 virtual int GetCapturerCount() const = 0; 293 294 // Indicates whether this tab should be considered crashed. The setter will 295 // also notify the delegate when the flag is changed. 296 virtual bool IsCrashed() const = 0; 297 virtual void SetIsCrashed(base::TerminationStatus status, int error_code) = 0; 298 299 virtual base::TerminationStatus GetCrashedStatus() const = 0; 300 301 // Whether the tab is in the process of being destroyed. 302 virtual bool IsBeingDestroyed() const = 0; 303 304 // Convenience method for notifying the delegate of a navigation state 305 // change. See InvalidateType enum. 306 virtual void NotifyNavigationStateChanged(unsigned changed_flags) = 0; 307 308 // Get the last time that the WebContents was made active (either when it was 309 // created or shown with WasShown()). 310 virtual base::TimeTicks GetLastActiveTime() const = 0; 311 312 // Invoked when the WebContents becomes shown/hidden. 313 virtual void WasShown() = 0; 314 virtual void WasHidden() = 0; 315 316 // Returns true if the before unload and unload listeners need to be 317 // fired. The value of this changes over time. For example, if true and the 318 // before unload listener is executed and allows the user to exit, then this 319 // returns false. 320 virtual bool NeedToFireBeforeUnload() = 0; 321 322 // Commands ------------------------------------------------------------------ 323 324 // Stop any pending navigation. 325 virtual void Stop() = 0; 326 327 // Creates a new WebContents with the same state as this one. The returned 328 // heap-allocated pointer is owned by the caller. 329 virtual WebContents* Clone() = 0; 330 331 // Views and focus ----------------------------------------------------------- 332 // Focuses the first (last if |reverse| is true) element in the page. 333 // Invoked when this tab is getting the focus through tab traversal (|reverse| 334 // is true when using Shift-Tab). 335 virtual void FocusThroughTabTraversal(bool reverse) = 0; 336 337 // Interstitials ------------------------------------------------------------- 338 339 // Various other systems need to know about our interstitials. 340 virtual bool ShowingInterstitialPage() const = 0; 341 342 // Returns the currently showing interstitial, NULL if no interstitial is 343 // showing. 344 virtual InterstitialPage* GetInterstitialPage() const = 0; 345 346 // Misc state & callbacks ---------------------------------------------------- 347 348 // Check whether we can do the saving page operation this page given its MIME 349 // type. 350 virtual bool IsSavable() = 0; 351 352 // Prepare for saving the current web page to disk. 353 virtual void OnSavePage() = 0; 354 355 // Save page with the main HTML file path, the directory for saving resources, 356 // and the save type: HTML only or complete web page. Returns true if the 357 // saving process has been initiated successfully. 358 virtual bool SavePage(const base::FilePath& main_file, 359 const base::FilePath& dir_path, 360 SavePageType save_type) = 0; 361 362 // Saves the given frame's URL to the local filesystem.. 363 virtual void SaveFrame(const GURL& url, 364 const Referrer& referrer) = 0; 365 366 // Generate an MHTML representation of the current page in the given file. 367 virtual void GenerateMHTML( 368 const base::FilePath& file, 369 const base::Callback<void( 370 int64 /* size of the file */)>& callback) = 0; 371 372 // Returns true if the active NavigationEntry's page_id equals page_id. 373 virtual bool IsActiveEntry(int32 page_id) = 0; 374 375 // Returns the contents MIME type after a navigation. 376 virtual const std::string& GetContentsMimeType() const = 0; 377 378 // Returns true if this WebContents will notify about disconnection. 379 virtual bool WillNotifyDisconnection() const = 0; 380 381 // Override the encoding and reload the page by sending down 382 // ViewMsg_SetPageEncoding to the renderer. |UpdateEncoding| is kinda 383 // the opposite of this, by which 'browser' is notified of 384 // the encoding of the current tab from 'renderer' (determined by 385 // auto-detect, http header, meta, bom detection, etc). 386 virtual void SetOverrideEncoding(const std::string& encoding) = 0; 387 388 // Remove any user-defined override encoding and reload by sending down 389 // ViewMsg_ResetPageEncodingToDefault to the renderer. 390 virtual void ResetOverrideEncoding() = 0; 391 392 // Returns the settings which get passed to the renderer. 393 virtual content::RendererPreferences* GetMutableRendererPrefs() = 0; 394 395 // Tells the tab to close now. The tab will take care not to close until it's 396 // out of nested message loops. 397 virtual void Close() = 0; 398 399 // A render view-originated drag has ended. Informs the render view host and 400 // WebContentsDelegate. 401 virtual void SystemDragEnded() = 0; 402 403 // Notification the user has made a gesture while focus was on the 404 // page. This is used to avoid uninitiated user downloads (aka carpet 405 // bombing), see DownloadRequestLimiter for details. 406 virtual void UserGestureDone() = 0; 407 408 // Indicates if this tab was explicitly closed by the user (control-w, close 409 // tab menu item...). This is false for actions that indirectly close the tab, 410 // such as closing the window. The setter is maintained by TabStripModel, and 411 // the getter only useful from within TAB_CLOSED notification 412 virtual void SetClosedByUserGesture(bool value) = 0; 413 virtual bool GetClosedByUserGesture() const = 0; 414 415 // Gets the zoom level for this tab. 416 virtual double GetZoomLevel() const = 0; 417 418 // Gets the zoom percent for this tab. 419 virtual int GetZoomPercent(bool* enable_increment, 420 bool* enable_decrement) const = 0; 421 422 // Opens view-source tab for this contents. 423 virtual void ViewSource() = 0; 424 425 virtual void ViewFrameSource(const GURL& url, 426 const PageState& page_state)= 0; 427 428 // Gets the minimum/maximum zoom percent. 429 virtual int GetMinimumZoomPercent() const = 0; 430 virtual int GetMaximumZoomPercent() const = 0; 431 432 // Gets the preferred size of the contents. 433 virtual gfx::Size GetPreferredSize() const = 0; 434 435 // Called when the reponse to a pending mouse lock request has arrived. 436 // Returns true if |allowed| is true and the mouse has been successfully 437 // locked. 438 virtual bool GotResponseToLockMouseRequest(bool allowed) = 0; 439 440 // Called when the user has selected a color in the color chooser. 441 virtual void DidChooseColorInColorChooser(SkColor color) = 0; 442 443 // Called when the color chooser has ended. 444 virtual void DidEndColorChooser() = 0; 445 446 // Returns true if the location bar should be focused by default rather than 447 // the page contents. The view calls this function when the tab is focused 448 // to see what it should do. 449 virtual bool FocusLocationBarByDefault() = 0; 450 451 // Does this have an opener associated with it? 452 virtual bool HasOpener() const = 0; 453 454 typedef base::Callback<void( 455 int, /* id */ 456 int, /* HTTP status code */ 457 const GURL&, /* image_url */ 458 const std::vector<SkBitmap>&, /* bitmaps */ 459 /* The sizes in pixel of the bitmaps before they were resized due to the 460 max bitmap size passed to DownloadImage(). Each entry in the bitmaps 461 vector corresponds to an entry in the sizes vector. If a bitmap was 462 resized, there should be a single returned bitmap. */ 463 const std::vector<gfx::Size>&)> 464 ImageDownloadCallback; 465 466 // Sends a request to download the given image |url| and returns the unique 467 // id of the download request. When the download is finished, |callback| will 468 // be called with the bitmaps received from the renderer. If |is_favicon| is 469 // true, the cookies are not sent and not accepted during download. 470 // Bitmaps with pixel sizes larger than |max_bitmap_size| are filtered out 471 // from the bitmap results. If there are no bitmap results <= 472 // |max_bitmap_size|, the smallest bitmap is resized to |max_bitmap_size| and 473 // is the only result. A |max_bitmap_size| of 0 means unlimited. 474 virtual int DownloadImage(const GURL& url, 475 bool is_favicon, 476 uint32_t max_bitmap_size, 477 const ImageDownloadCallback& callback) = 0; 478 479 // Returns true if the WebContents is responsible for displaying a subframe 480 // in a different process from its parent page. 481 // TODO: this doesn't really belong here. With site isolation, this should be 482 // removed since we can then embed iframes in different processes. 483 virtual bool IsSubframe() const = 0; 484 485 // Sets the zoom level for the current page and all BrowserPluginGuests 486 // within the page. 487 virtual void SetZoomLevel(double level) = 0; 488 489 // Finds text on a page. 490 virtual void Find(int request_id, 491 const base::string16& search_text, 492 const blink::WebFindOptions& options) = 0; 493 494 // Notifies the renderer that the user has closed the FindInPage window 495 // (and what action to take regarding the selection). 496 virtual void StopFinding(StopFindAction action) = 0; 497 498#if defined(OS_ANDROID) 499 CONTENT_EXPORT static WebContents* FromJavaWebContents( 500 jobject jweb_contents_android); 501 virtual base::android::ScopedJavaLocalRef<jobject> GetJavaWebContents() = 0; 502#endif // OS_ANDROID 503 504 private: 505 // This interface should only be implemented inside content. 506 friend class WebContentsImpl; 507 WebContents() {} 508}; 509 510} // namespace content 511 512#endif // CONTENT_PUBLIC_BROWSER_WEB_CONTENTS_H_ 513