navigation_controller.h revision d0247b1b59f9c528cb6df88b4f2b9afaf80d181e
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_NAVIGATION_CONTROLLER_H_ 6#define CONTENT_PUBLIC_BROWSER_NAVIGATION_CONTROLLER_H_ 7 8#include <map> 9#include <string> 10#include <vector> 11 12#include "base/memory/ref_counted.h" 13#include "base/strings/string16.h" 14#include "content/common/content_export.h" 15#include "content/public/browser/global_request_id.h" 16#include "content/public/common/page_transition_types.h" 17#include "content/public/common/referrer.h" 18#include "url/gurl.h" 19 20namespace base { 21 22class RefCountedMemory; 23 24} // namespace base 25 26namespace content { 27 28class BrowserContext; 29class NavigationEntry; 30class SessionStorageNamespace; 31class WebContents; 32 33// Used to store the mapping of a StoragePartition id to 34// SessionStorageNamespace. 35typedef std::map<std::string, scoped_refptr<SessionStorageNamespace> > 36 SessionStorageNamespaceMap; 37 38// A NavigationController maintains the back-forward list for a WebContents and 39// manages all navigation within that list. 40// 41// Each NavigationController belongs to one WebContents; each WebContents has 42// exactly one NavigationController. 43class NavigationController { 44 public: 45 enum ReloadType { 46 NO_RELOAD, // Normal load. 47 RELOAD, // Normal (cache-validating) reload. 48 RELOAD_IGNORING_CACHE, // Reload bypassing the cache (shift-reload). 49 RELOAD_ORIGINAL_REQUEST_URL // Reload using the original request URL. 50 }; 51 52 // Load type used in LoadURLParams. 53 enum LoadURLType { 54 // For loads that do not fall into any types below. 55 LOAD_TYPE_DEFAULT, 56 57 // An http post load request initiated from browser side. 58 // The post data is passed in |browser_initiated_post_data|. 59 LOAD_TYPE_BROWSER_INITIATED_HTTP_POST, 60 61 // Loads a 'data:' scheme URL with specified base URL and a history entry 62 // URL. This is only safe to be used for browser-initiated data: URL 63 // navigations, since it shows arbitrary content as if it comes from 64 // |virtual_url_for_data_url|. 65 LOAD_TYPE_DATA 66 67 // Adding new LoadURLType? Also update LoadUrlParams.java static constants. 68 }; 69 70 // User agent override type used in LoadURLParams. 71 enum UserAgentOverrideOption { 72 // Use the override value from the previous NavigationEntry in the 73 // NavigationController. 74 UA_OVERRIDE_INHERIT, 75 76 // Use the default user agent. 77 UA_OVERRIDE_FALSE, 78 79 // Use the user agent override, if it's available. 80 UA_OVERRIDE_TRUE 81 82 // Adding new UserAgentOverrideOption? Also update LoadUrlParams.java 83 // static constants. 84 }; 85 86 enum RestoreType { 87 // Indicates the restore is from the current session. For example, restoring 88 // a closed tab. 89 RESTORE_CURRENT_SESSION, 90 91 // Restore from the previous session. 92 RESTORE_LAST_SESSION_EXITED_CLEANLY, 93 RESTORE_LAST_SESSION_CRASHED, 94 }; 95 96 // Creates a navigation entry and translates the virtual url to a real one. 97 // This is a general call; prefer LoadURL[FromRenderer]/TransferURL below. 98 // Extra headers are separated by \n. 99 CONTENT_EXPORT static NavigationEntry* CreateNavigationEntry( 100 const GURL& url, 101 const Referrer& referrer, 102 PageTransition transition, 103 bool is_renderer_initiated, 104 const std::string& extra_headers, 105 BrowserContext* browser_context); 106 107 // Extra optional parameters for LoadURLWithParams. 108 struct CONTENT_EXPORT LoadURLParams { 109 // The url to load. This field is required. 110 GURL url; 111 112 // See LoadURLType comments above. 113 LoadURLType load_type; 114 115 // PageTransition for this load. See PageTransition for details. 116 // Note the default value in constructor below. 117 PageTransition transition_type; 118 119 // Referrer for this load. Empty if none. 120 Referrer referrer; 121 122 // Extra headers for this load, separated by \n. 123 std::string extra_headers; 124 125 // True for renderer-initiated navigations. This is 126 // important for tracking whether to display pending URLs. 127 bool is_renderer_initiated; 128 129 // User agent override for this load. See comments in 130 // UserAgentOverrideOption definition. 131 UserAgentOverrideOption override_user_agent; 132 133 // Marks the new navigation as being transferred from one RVH to another. 134 // In this case the browser can recycle the old request once the new 135 // renderer wants to navigate. Identifies the request ID of the old request. 136 GlobalRequestID transferred_global_request_id; 137 138 // Used in LOAD_TYPE_DATA loads only. Used for specifying a base URL 139 // for pages loaded via data URLs. 140 GURL base_url_for_data_url; 141 142 // Used in LOAD_TYPE_DATA loads only. URL displayed to the user for 143 // data loads. 144 GURL virtual_url_for_data_url; 145 146 // Used in LOAD_TYPE_BROWSER_INITIATED_HTTP_POST loads only. Carries the 147 // post data of the load. Ownership is transferred to NavigationController 148 // after LoadURLWithParams call. 149 scoped_refptr<base::RefCountedMemory> browser_initiated_post_data; 150 151 // True if this URL should be able to access local resources. 152 bool can_load_local_resources; 153 154 // Indicates whether this navigation should replace the current 155 // navigation entry. 156 bool should_replace_current_entry; 157 158 // Used to specify which frame to navigate. If empty, the main frame is 159 // navigated. This is currently only used in tests. 160 std::string frame_name; 161 162 // Indicates that during this navigation, the session history should be 163 // cleared such that the resulting page is the first and only entry of the 164 // session history. 165 // 166 // The clearing is done asynchronously, and completes when this navigation 167 // commits. 168 bool should_clear_history_list; 169 170 explicit LoadURLParams(const GURL& url); 171 ~LoadURLParams(); 172 173 // Allows copying of LoadURLParams struct. 174 LoadURLParams(const LoadURLParams& other); 175 LoadURLParams& operator=(const LoadURLParams& other); 176 }; 177 178 // Disables checking for a repost and prompting the user. This is used during 179 // testing. 180 CONTENT_EXPORT static void DisablePromptOnRepost(); 181 182 virtual ~NavigationController() {} 183 184 // Returns the web contents associated with this controller. It can never be 185 // NULL. 186 virtual WebContents* GetWebContents() const = 0; 187 188 // Get/set the browser context for this controller. It can never be NULL. 189 virtual BrowserContext* GetBrowserContext() const = 0; 190 virtual void SetBrowserContext(BrowserContext* browser_context) = 0; 191 192 // Initializes this NavigationController with the given saved navigations, 193 // using |selected_navigation| as the currently loaded entry. Before this call 194 // the controller should be unused (there should be no current entry). |type| 195 // indicates where the restor comes from. This takes ownership of the 196 // NavigationEntrys in |entries| and clears it out. This is used for session 197 // restore. 198 virtual void Restore(int selected_navigation, 199 RestoreType type, 200 std::vector<NavigationEntry*>* entries) = 0; 201 202 // Entries ------------------------------------------------------------------- 203 204 // There are two basic states for entries: pending and committed. When an 205 // entry is navigated to, a request is sent to the server. While that request 206 // has not been responded to, the NavigationEntry is pending. Once data is 207 // received for that entry, that NavigationEntry is committed. 208 209 // A transient entry is an entry that, when the user navigates away, is 210 // removed and discarded rather than being added to the back-forward list. 211 // Transient entries are useful for interstitial pages and the like. 212 213 // Active entry -------------------------------------------------------------- 214 215 // THIS IS DEPRECATED. DO NOT USE. Use GetVisibleEntry instead. 216 // 217 // Returns the active entry, which is the transient entry if any, the pending 218 // entry if a navigation is in progress or the last committed entry otherwise. 219 // NOTE: This can be NULL!! 220 // 221 // If you are trying to get the current state of the NavigationController, 222 // this is the method you will typically want to call. If you want to display 223 // the active entry to the user (e.g., in the location bar), use 224 // GetVisibleEntry instead. 225 virtual NavigationEntry* GetActiveEntry() const = 0; 226 227 // Returns the same entry as GetActiveEntry, except that it ignores pending 228 // history navigation entries. This should be used when displaying info to 229 // the user, so that the location bar and other indicators do not update for 230 // a back/forward navigation until the pending entry commits. This approach 231 // guards against URL spoofs on slow history navigations. 232 virtual NavigationEntry* GetVisibleEntry() const = 0; 233 234 // Returns the index from which we would go back/forward or reload. This is 235 // the last_committed_entry_index_ if pending_entry_index_ is -1. Otherwise, 236 // it is the pending_entry_index_. 237 virtual int GetCurrentEntryIndex() const = 0; 238 239 // Returns the last committed entry, which may be null if there are no 240 // committed entries. 241 virtual NavigationEntry* GetLastCommittedEntry() const = 0; 242 243 // Returns the index of the last committed entry. 244 virtual int GetLastCommittedEntryIndex() const = 0; 245 246 // Returns true if the source for the current entry can be viewed. 247 virtual bool CanViewSource() const = 0; 248 249 // Navigation list ----------------------------------------------------------- 250 251 // Returns the number of entries in the NavigationController, excluding 252 // the pending entry if there is one, but including the transient entry if 253 // any. 254 virtual int GetEntryCount() const = 0; 255 256 virtual NavigationEntry* GetEntryAtIndex(int index) const = 0; 257 258 // Returns the entry at the specified offset from current. Returns NULL 259 // if out of bounds. 260 virtual NavigationEntry* GetEntryAtOffset(int offset) const = 0; 261 262 // Pending entry ------------------------------------------------------------- 263 264 // Discards the pending and transient entries if any. 265 virtual void DiscardNonCommittedEntries() = 0; 266 267 // Returns the pending entry corresponding to the navigation that is 268 // currently in progress, or null if there is none. 269 virtual NavigationEntry* GetPendingEntry() const = 0; 270 271 // Returns the index of the pending entry or -1 if the pending entry 272 // corresponds to a new navigation (created via LoadURL). 273 virtual int GetPendingEntryIndex() const = 0; 274 275 // Transient entry ----------------------------------------------------------- 276 277 // Returns the transient entry if any. This is an entry which is removed and 278 // discarded if any navigation occurs. Note that the returned entry is owned 279 // by the navigation controller and may be deleted at any time. 280 virtual NavigationEntry* GetTransientEntry() const = 0; 281 282 // Adds an entry that is returned by GetActiveEntry(). The entry is 283 // transient: any navigation causes it to be removed and discarded. The 284 // NavigationController becomes the owner of |entry| and deletes it when 285 // it discards it. This is useful with interstitial pages that need to be 286 // represented as an entry, but should go away when the user navigates away 287 // from them. 288 // Note that adding a transient entry does not change the active contents. 289 virtual void SetTransientEntry(NavigationEntry* entry) = 0; 290 291 // New navigations ----------------------------------------------------------- 292 293 // Loads the specified URL, specifying extra http headers to add to the 294 // request. Extra headers are separated by \n. 295 virtual void LoadURL(const GURL& url, 296 const Referrer& referrer, 297 PageTransition type, 298 const std::string& extra_headers) = 0; 299 300 // More general version of LoadURL. See comments in LoadURLParams for 301 // using |params|. 302 virtual void LoadURLWithParams(const LoadURLParams& params) = 0; 303 304 // Loads the current page if this NavigationController was restored from 305 // history and the current page has not loaded yet. 306 virtual void LoadIfNecessary() = 0; 307 308 // Renavigation -------------------------------------------------------------- 309 310 // Navigation relative to the "current entry" 311 virtual bool CanGoBack() const = 0; 312 virtual bool CanGoForward() const = 0; 313 virtual bool CanGoToOffset(int offset) const = 0; 314 virtual void GoBack() = 0; 315 virtual void GoForward() = 0; 316 317 // Navigates to the specified absolute index. 318 virtual void GoToIndex(int index) = 0; 319 320 // Navigates to the specified offset from the "current entry". Does nothing if 321 // the offset is out of bounds. 322 virtual void GoToOffset(int offset) = 0; 323 324 // Reloads the current entry. If |check_for_repost| is true and the current 325 // entry has POST data the user is prompted to see if they really want to 326 // reload the page. In nearly all cases pass in true. If a transient entry 327 // is showing, initiates a new navigation to its URL. 328 virtual void Reload(bool check_for_repost) = 0; 329 330 // Like Reload(), but don't use caches (aka "shift-reload"). 331 virtual void ReloadIgnoringCache(bool check_for_repost) = 0; 332 333 // Reloads the current entry using the original URL used to create it. This 334 // is used for cases where the user wants to refresh a page using a different 335 // user agent after following a redirect. 336 virtual void ReloadOriginalRequestURL(bool check_for_repost) = 0; 337 338 // Removing of entries ------------------------------------------------------- 339 340 // Removes the entry at the specified |index|. This call discards any 341 // transient entries. If the index is the last committed index or the pending 342 // entry, this does nothing and returns false. 343 virtual bool RemoveEntryAtIndex(int index) = 0; 344 345 // Random -------------------------------------------------------------------- 346 347 // Session storage depends on dom_storage that depends on WebKit::WebString, 348 // which cannot be used on iOS. 349#if !defined(OS_IOS) 350 // Returns all the SessionStorageNamespace objects that this 351 // NavigationController knows about. 352 virtual const SessionStorageNamespaceMap& 353 GetSessionStorageNamespaceMap() const = 0; 354 355 // TODO(ajwong): Remove this once prerendering, instant, and session restore 356 // are migrated. 357 virtual SessionStorageNamespace* GetDefaultSessionStorageNamespace() = 0; 358#endif 359 360 // Sets the max restored page ID this NavigationController has seen, if it 361 // was restored from a previous session. 362 virtual void SetMaxRestoredPageID(int32 max_id) = 0; 363 364 // Returns the largest restored page ID seen in this navigation controller, 365 // if it was restored from a previous session. (-1 otherwise) 366 virtual int32 GetMaxRestoredPageID() const = 0; 367 368 // Returns true if a reload happens when activated (SetActive(true) is 369 // invoked). This is true for session/tab restore and cloned tabs. 370 virtual bool NeedsReload() const = 0; 371 372 // Cancels a repost that brought up a warning. 373 virtual void CancelPendingReload() = 0; 374 // Continues a repost that brought up a warning. 375 virtual void ContinuePendingReload() = 0; 376 377 // Returns true if we are navigating to the URL the tab is opened with. 378 // Returns false after the initial navigation has committed. 379 virtual bool IsInitialNavigation() const = 0; 380 381 // Broadcasts the NOTIFICATION_NAV_ENTRY_CHANGED notification for the given 382 // entry (which must be at the given index). This will keep things in sync 383 // like the saved session. 384 virtual void NotifyEntryChanged(const NavigationEntry* entry, int index) = 0; 385 386 // Copies the navigation state from the given controller to this one. This 387 // one should be empty (just created). 388 virtual void CopyStateFrom(const NavigationController& source) = 0; 389 390 // A variant of CopyStateFrom. Removes all entries from this except the last 391 // committed entry, and inserts all entries from |source| before and including 392 // its last committed entry. For example: 393 // source: A B *C* D 394 // this: E F *G* 395 // result: A B C *G* 396 // If there is a pending entry after *G* in |this|, it is also preserved. 397 // This ignores any pending or transient entries in |source|. Callers must 398 // ensure that |CanPruneAllButVisible| returns true before calling this, or it 399 // will crash. 400 virtual void CopyStateFromAndPrune(NavigationController* source) = 0; 401 402 // Returns whether it is safe to call PruneAllButVisible or 403 // CopyStateFromAndPrune. There must be a last committed entry, no transient 404 // entry, and if there is a pending entry, it must be new and not an existing 405 // entry. 406 // 407 // If there were no last committed entry, the pending entry might not commit, 408 // leaving us with a blank page. This is unsafe when used with 409 // |CopyStateFromAndPrune|, which would show an existing entry above the blank 410 // page. 411 // If there were a transient entry, we would not want to prune the other 412 // entries, which the transient entry could be referring to. 413 // If there were an existing pending entry, we could not prune the last 414 // committed entry, in case it did not commit. That would leave us with no 415 // sensible place to put the pending entry when it did commit, after all other 416 // entries are pruned. For example, it could be going back several entries. 417 // (New pending entries are safe, because they can always commit to the end.) 418 virtual bool CanPruneAllButVisible() = 0; 419 420 // Removes all the entries except the last committed entry. If there is a new 421 // pending navigation it is preserved. Callers must ensure 422 // |CanPruneAllButVisible| returns true before calling this, or it will crash. 423 virtual void PruneAllButVisible() = 0; 424 425 // Clears all screenshots associated with navigation entries in this 426 // controller. Useful to reduce memory consumption in low-memory situations. 427 virtual void ClearAllScreenshots() = 0; 428 429 private: 430 // This interface should only be implemented inside content. 431 friend class NavigationControllerImpl; 432 NavigationController() {} 433}; 434 435} // namespace content 436 437#endif // CONTENT_PUBLIC_BROWSER_NAVIGATION_CONTROLLER_H_ 438