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_NAVIGATION_CONTROLLER_H_
6 #define CONTENT_PUBLIC_BROWSER_NAVIGATION_CONTROLLER_H_
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/browser/session_storage_namespace.h"
17 #include "content/public/common/referrer.h"
18 #include "ui/base/page_transition_types.h"
23 class RefCountedMemory;
30 class NavigationEntry;
33 // A NavigationController maintains the back-forward list for a WebContents and
34 // manages all navigation within that list.
36 // Each NavigationController belongs to one WebContents; each WebContents has
37 // exactly one NavigationController.
38 class NavigationController {
41 NO_RELOAD, // Normal load.
42 RELOAD, // Normal (cache-validating) reload.
43 RELOAD_IGNORING_CACHE, // Reload bypassing the cache (shift-reload).
44 RELOAD_ORIGINAL_REQUEST_URL // Reload using the original request URL.
47 // Load type used in LoadURLParams.
49 // For loads that do not fall into any types below.
52 // An http post load request initiated from browser side.
53 // The post data is passed in |browser_initiated_post_data|.
54 LOAD_TYPE_BROWSER_INITIATED_HTTP_POST,
56 // Loads a 'data:' scheme URL with specified base URL and a history entry
57 // URL. This is only safe to be used for browser-initiated data: URL
58 // navigations, since it shows arbitrary content as if it comes from
59 // |virtual_url_for_data_url|.
62 // Adding new LoadURLType? Also update LoadUrlParams.java static constants.
65 // User agent override type used in LoadURLParams.
66 enum UserAgentOverrideOption {
67 // Use the override value from the previous NavigationEntry in the
68 // NavigationController.
71 // Use the default user agent.
74 // Use the user agent override, if it's available.
77 // Adding new UserAgentOverrideOption? Also update LoadUrlParams.java
82 // Indicates the restore is from the current session. For example, restoring
84 RESTORE_CURRENT_SESSION,
86 // Restore from the previous session.
87 RESTORE_LAST_SESSION_EXITED_CLEANLY,
88 RESTORE_LAST_SESSION_CRASHED,
91 // Creates a navigation entry and translates the virtual url to a real one.
92 // This is a general call; prefer LoadURL[FromRenderer]/TransferURL below.
93 // Extra headers are separated by \n.
94 CONTENT_EXPORT static NavigationEntry* CreateNavigationEntry(
96 const Referrer& referrer,
97 ui::PageTransition transition,
98 bool is_renderer_initiated,
99 const std::string& extra_headers,
100 BrowserContext* browser_context);
102 // Extra optional parameters for LoadURLWithParams.
103 struct CONTENT_EXPORT LoadURLParams {
104 // The url to load. This field is required.
107 // See LoadURLType comments above.
108 LoadURLType load_type;
110 // PageTransition for this load. See PageTransition for details.
111 // Note the default value in constructor below.
112 ui::PageTransition transition_type;
114 // The FrameTreeNode ID for the frame to navigate, or -1 for the main frame.
115 int64 frame_tree_node_id;
117 // Referrer for this load. Empty if none.
120 // Any redirect URLs that occurred for this navigation before |url|.
121 // Defaults to an empty vector.
122 std::vector<GURL> redirect_chain;
124 // Extra headers for this load, separated by \n.
125 std::string extra_headers;
127 // True for renderer-initiated navigations. This is
128 // important for tracking whether to display pending URLs.
129 bool is_renderer_initiated;
131 // User agent override for this load. See comments in
132 // UserAgentOverrideOption definition.
133 UserAgentOverrideOption override_user_agent;
135 // Marks the new navigation as being transferred from one RVH to another.
136 // In this case the browser can recycle the old request once the new
137 // renderer wants to navigate. Identifies the request ID of the old request.
138 GlobalRequestID transferred_global_request_id;
140 // Used in LOAD_TYPE_DATA loads only. Used for specifying a base URL
141 // for pages loaded via data URLs.
142 GURL base_url_for_data_url;
144 // Used in LOAD_TYPE_DATA loads only. URL displayed to the user for
146 GURL virtual_url_for_data_url;
148 // Used in LOAD_TYPE_BROWSER_INITIATED_HTTP_POST loads only. Carries the
149 // post data of the load. Ownership is transferred to NavigationController
150 // after LoadURLWithParams call.
151 scoped_refptr<base::RefCountedMemory> browser_initiated_post_data;
153 // True if this URL should be able to access local resources.
154 bool can_load_local_resources;
156 // Indicates whether this navigation should replace the current
158 bool should_replace_current_entry;
160 // Used to specify which frame to navigate. If empty, the main frame is
161 // navigated. This is currently only used in tests.
162 std::string frame_name;
164 // Indicates that during this navigation, the session history should be
165 // cleared such that the resulting page is the first and only entry of the
168 // The clearing is done asynchronously, and completes when this navigation
170 bool should_clear_history_list;
172 explicit LoadURLParams(const GURL& url);
175 // Allows copying of LoadURLParams struct.
176 LoadURLParams(const LoadURLParams& other);
177 LoadURLParams& operator=(const LoadURLParams& other);
180 // Disables checking for a repost and prompting the user. This is used during
182 CONTENT_EXPORT static void DisablePromptOnRepost();
184 virtual ~NavigationController() {}
186 // Returns the web contents associated with this controller. It can never be
188 virtual WebContents* GetWebContents() const = 0;
190 // Get/set the browser context for this controller. It can never be NULL.
191 virtual BrowserContext* GetBrowserContext() const = 0;
192 virtual void SetBrowserContext(BrowserContext* browser_context) = 0;
194 // Initializes this NavigationController with the given saved navigations,
195 // using |selected_navigation| as the currently loaded entry. Before this call
196 // the controller should be unused (there should be no current entry). |type|
197 // indicates where the restor comes from. This takes ownership of the
198 // NavigationEntrys in |entries| and clears it out. This is used for session
200 virtual void Restore(int selected_navigation,
202 std::vector<NavigationEntry*>* entries) = 0;
204 // Entries -------------------------------------------------------------------
206 // There are two basic states for entries: pending and committed. When an
207 // entry is navigated to, a request is sent to the server. While that request
208 // has not been responded to, the NavigationEntry is pending. Once data is
209 // received for that entry, that NavigationEntry is committed.
211 // A transient entry is an entry that, when the user navigates away, is
212 // removed and discarded rather than being added to the back-forward list.
213 // Transient entries are useful for interstitial pages and the like.
215 // Active entry --------------------------------------------------------------
217 // THIS IS DEPRECATED. DO NOT USE. Use GetVisibleEntry instead.
218 // See http://crbug.com/273710.
220 // Returns the active entry, which is the transient entry if any, the pending
221 // entry if a navigation is in progress or the last committed entry otherwise.
222 // NOTE: This can be NULL!!
223 virtual NavigationEntry* GetActiveEntry() const = 0;
225 // Returns the entry that should be displayed to the user in the address bar.
226 // This is the transient entry if any, the pending entry if a navigation is
227 // in progress *and* is safe to display to the user (see below), or the last
228 // committed entry otherwise.
229 // NOTE: This can be NULL if no entry has committed!
231 // A pending entry is safe to display if it started in the browser process or
232 // if it's a renderer-initiated navigation in a new tab which hasn't been
233 // accessed by another tab. (If it has been accessed, it risks a URL spoof.)
234 virtual NavigationEntry* GetVisibleEntry() const = 0;
236 // Returns the index from which we would go back/forward or reload. This is
237 // the last_committed_entry_index_ if pending_entry_index_ is -1. Otherwise,
238 // it is the pending_entry_index_.
239 virtual int GetCurrentEntryIndex() const = 0;
241 // Returns the last committed entry, which may be null if there are no
242 // committed entries.
243 virtual NavigationEntry* GetLastCommittedEntry() const = 0;
245 // Returns the index of the last committed entry.
246 virtual int GetLastCommittedEntryIndex() const = 0;
248 // Returns true if the source for the current entry can be viewed.
249 virtual bool CanViewSource() const = 0;
251 // Navigation list -----------------------------------------------------------
253 // Returns the number of entries in the NavigationController, excluding
254 // the pending entry if there is one, but including the transient entry if
256 virtual int GetEntryCount() const = 0;
258 virtual NavigationEntry* GetEntryAtIndex(int index) const = 0;
260 // Returns the entry at the specified offset from current. Returns NULL
262 virtual NavigationEntry* GetEntryAtOffset(int offset) const = 0;
264 // Pending entry -------------------------------------------------------------
266 // Discards the pending and transient entries if any.
267 virtual void DiscardNonCommittedEntries() = 0;
269 // Returns the pending entry corresponding to the navigation that is
270 // currently in progress, or null if there is none.
271 virtual NavigationEntry* GetPendingEntry() const = 0;
273 // Returns the index of the pending entry or -1 if the pending entry
274 // corresponds to a new navigation (created via LoadURL).
275 virtual int GetPendingEntryIndex() const = 0;
277 // Transient entry -----------------------------------------------------------
279 // Returns the transient entry if any. This is an entry which is removed and
280 // discarded if any navigation occurs. Note that the returned entry is owned
281 // by the navigation controller and may be deleted at any time.
282 virtual NavigationEntry* GetTransientEntry() const = 0;
284 // Adds an entry that is returned by GetActiveEntry(). The entry is
285 // transient: any navigation causes it to be removed and discarded. The
286 // NavigationController becomes the owner of |entry| and deletes it when
287 // it discards it. This is useful with interstitial pages that need to be
288 // represented as an entry, but should go away when the user navigates away
290 // Note that adding a transient entry does not change the active contents.
291 virtual void SetTransientEntry(NavigationEntry* entry) = 0;
293 // New navigations -----------------------------------------------------------
295 // Loads the specified URL, specifying extra http headers to add to the
296 // request. Extra headers are separated by \n.
297 virtual void LoadURL(const GURL& url,
298 const Referrer& referrer,
299 ui::PageTransition type,
300 const std::string& extra_headers) = 0;
302 // More general version of LoadURL. See comments in LoadURLParams for
304 virtual void LoadURLWithParams(const LoadURLParams& params) = 0;
306 // Loads the current page if this NavigationController was restored from
307 // history and the current page has not loaded yet or if the load was
308 // explicitly requested using SetNeedsReload().
309 virtual void LoadIfNecessary() = 0;
311 // Renavigation --------------------------------------------------------------
313 // Navigation relative to the "current entry"
314 virtual bool CanGoBack() const = 0;
315 virtual bool CanGoForward() const = 0;
316 virtual bool CanGoToOffset(int offset) const = 0;
317 virtual void GoBack() = 0;
318 virtual void GoForward() = 0;
320 // Navigates to the specified absolute index.
321 virtual void GoToIndex(int index) = 0;
323 // Navigates to the specified offset from the "current entry". Does nothing if
324 // the offset is out of bounds.
325 virtual void GoToOffset(int offset) = 0;
327 // Reloads the current entry. If |check_for_repost| is true and the current
328 // entry has POST data the user is prompted to see if they really want to
329 // reload the page. In nearly all cases pass in true. If a transient entry
330 // is showing, initiates a new navigation to its URL.
331 virtual void Reload(bool check_for_repost) = 0;
333 // Like Reload(), but don't use caches (aka "shift-reload").
334 virtual void ReloadIgnoringCache(bool check_for_repost) = 0;
336 // Reloads the current entry using the original URL used to create it. This
337 // is used for cases where the user wants to refresh a page using a different
338 // user agent after following a redirect.
339 virtual void ReloadOriginalRequestURL(bool check_for_repost) = 0;
341 // Removing of entries -------------------------------------------------------
343 // Removes the entry at the specified |index|. This call discards any
344 // transient entries. If the index is the last committed index or the pending
345 // entry, this does nothing and returns false.
346 virtual bool RemoveEntryAtIndex(int index) = 0;
348 // Random --------------------------------------------------------------------
350 // Session storage depends on dom_storage that depends on blink::WebString,
351 // which cannot be used on iOS.
353 // Returns all the SessionStorageNamespace objects that this
354 // NavigationController knows about, the map key is a StoragePartition id.
355 virtual const SessionStorageNamespaceMap&
356 GetSessionStorageNamespaceMap() const = 0;
358 // TODO(ajwong): Remove this once prerendering, instant, and session restore
360 virtual SessionStorageNamespace* GetDefaultSessionStorageNamespace() = 0;
363 // Sets the max restored page ID this NavigationController has seen, if it
364 // was restored from a previous session.
365 virtual void SetMaxRestoredPageID(int32 max_id) = 0;
367 // Returns the largest restored page ID seen in this navigation controller,
368 // if it was restored from a previous session. (-1 otherwise)
369 virtual int32 GetMaxRestoredPageID() const = 0;
371 // Returns true if a reload happens when activated (SetActive(true) is
372 // invoked). This is true for session/tab restore, cloned tabs and tabs that
373 // requested a reload (using SetNeedsReload()) after their renderer was
375 virtual bool NeedsReload() const = 0;
377 // Request a reload to happen when activated. This can be used when a renderer
378 // backing a background tab is killed by the system on Android or ChromeOS.
379 virtual void SetNeedsReload() = 0;
381 // Cancels a repost that brought up a warning.
382 virtual void CancelPendingReload() = 0;
383 // Continues a repost that brought up a warning.
384 virtual void ContinuePendingReload() = 0;
386 // Returns true if we are navigating to the URL the tab is opened with.
387 // Returns false after the initial navigation has committed.
388 virtual bool IsInitialNavigation() const = 0;
390 // Broadcasts the NOTIFICATION_NAV_ENTRY_CHANGED notification for the given
391 // entry (which must be at the given index). This will keep things in sync
392 // like the saved session.
393 virtual void NotifyEntryChanged(const NavigationEntry* entry, int index) = 0;
395 // Copies the navigation state from the given controller to this one. This
396 // one should be empty (just created).
397 virtual void CopyStateFrom(const NavigationController& source) = 0;
399 // A variant of CopyStateFrom. Removes all entries from this except the last
400 // committed entry, and inserts all entries from |source| before and including
401 // its last committed entry. For example:
405 // If there is a pending entry after *G* in |this|, it is also preserved.
406 // If |replace_entry| is true, the current entry in |source| is replaced. So
407 // the result above would be A B *G*.
408 // This ignores any pending or transient entries in |source|. Callers must
409 // ensure that |CanPruneAllButLastCommitted| returns true before calling this,
411 virtual void CopyStateFromAndPrune(NavigationController* source,
412 bool replace_entry) = 0;
414 // Returns whether it is safe to call PruneAllButLastCommitted or
415 // CopyStateFromAndPrune. There must be a last committed entry, no transient
416 // entry, and if there is a pending entry, it must be new and not an existing
419 // If there were no last committed entry, the pending entry might not commit,
420 // leaving us with a blank page. This is unsafe when used with
421 // |CopyStateFromAndPrune|, which would show an existing entry above the blank
423 // If there were a transient entry, we would not want to prune the other
424 // entries, which the transient entry could be referring to.
425 // If there were an existing pending entry, we could not prune the last
426 // committed entry, in case it did not commit. That would leave us with no
427 // sensible place to put the pending entry when it did commit, after all other
428 // entries are pruned. For example, it could be going back several entries.
429 // (New pending entries are safe, because they can always commit to the end.)
430 virtual bool CanPruneAllButLastCommitted() = 0;
432 // Removes all the entries except the last committed entry. If there is a new
433 // pending navigation it is preserved. Callers must ensure
434 // |CanPruneAllButLastCommitted| returns true before calling this, or it will
436 virtual void PruneAllButLastCommitted() = 0;
438 // Clears all screenshots associated with navigation entries in this
439 // controller. Useful to reduce memory consumption in low-memory situations.
440 virtual void ClearAllScreenshots() = 0;
443 // This interface should only be implemented inside content.
444 friend class NavigationControllerImpl;
445 NavigationController() {}
448 } // namespace content
450 #endif // CONTENT_PUBLIC_BROWSER_NAVIGATION_CONTROLLER_H_