content/public/browser/navigation_handle.h

   1 // Copyright 2015 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_HANDLE_H_
   6 #define CONTENT_PUBLIC_BROWSER_NAVIGATION_HANDLE_H_
   7
   8 #include "content/common/content_export.h"
   9 #include "content/public/browser/navigation_throttle.h"
  10 #include "content/public/common/referrer.h"
  11 #include "net/base/net_errors.h"
  12 #include "ui/base/page_transition_types.h"
  13
  14 class GURL;
  15
  16 namespace content {
  17 class NavigationThrottle;
  18 class WebContents;
  19
  20 // A NavigationHandle tracks information related to a single navigation.
  21 class CONTENT_EXPORT NavigationHandle {
  22  public:
  23   virtual ~NavigationHandle() {}
  24
  25   // Parameters available at navigation start time -----------------------------
  26   //
  27   // These parameters are always available during the navigation. Note that
  28   // some may change during navigation (e.g. due to server redirects).
  29
  30   // The URL the frame is navigating to. This may change during the navigation
  31   // when encountering a server redirect.
  32   virtual const GURL& GetURL() = 0;
  33
  34   // Whether the navigation is taking place in the main frame or in a subframe.
  35   // This remains constant over the navigation lifetime.
  36   virtual bool IsInMainFrame() = 0;
  37
  38   // The WebContents the navigation is taking place in.
  39   WebContents* GetWebContents();
  40
  41   // Parameters available at network request start time ------------------------
  42   //
  43   // The following parameters are only available when the network request is
  44   // made for the navigation (or at commit time if no network request is made).
  45   // This corresponds to NavigationThrottle::WillSendRequest. They should not
  46   // be queried before that.
  47
  48   // Whether the navigation is a POST or a GET. This may change during the
  49   // navigation when encountering a server redirect.
  50   virtual bool IsPost() = 0;
  51
  52   // Returns a sanitized version of the referrer for this request.
  53   virtual const Referrer& GetReferrer() = 0;
  54
  55   // Whether the navigation was initiated by a user gesture. Note that this
  56   // will return false for browser-initiated navigations.
  57   // TODO(clamy): when PlzNavigate launches, this should return true for
  58   // browser-initiated navigations.
  59   virtual bool HasUserGesture() = 0;
  60
  61   // Returns the page transition type.
  62   virtual ui::PageTransition GetPageTransition() = 0;
  63
  64   // Whether the target URL cannot be handled by the browser's internal protocol
  65   // handlers.
  66   virtual bool IsExternalProtocol() = 0;
  67
  68   // Navigation control flow --------------------------------------------------
  69
  70   // The net error code if an error happened prior to commit. Otherwise it will
  71   // be net::OK.
  72   virtual net::Error GetNetErrorCode() = 0;
  73
  74   // Whether the navigation happened in the same page. This is only known
  75   // after the navigation has committed. It is an error to call this method
  76   // before the navigation has committed.
  77   virtual bool IsSamePage() = 0;
  78
  79   // Whether the navigation has successfully committed a document.
  80   virtual bool HasCommittedDocument() = 0;
  81
  82   // Whether an error page has committed for the navigation.
  83   virtual bool HasCommittedErrorPage() = 0;
  84
  85   // Testing methods ----------------------------------------------------------
  86   //
  87   // The following methods should be used exclusively for writing unit tests.
  88
  89   static scoped_ptr<NavigationHandle> CreateNavigationHandleForTesting(
  90       const GURL& url,
  91       bool is_main_frame,
  92       WebContents* web_contents);
  93
  94   // Registers a NavigationThrottle for tests. The throttle can
  95   // modify the request, pause the request or cancel the request. This will
  96   // take ownership of the NavigationThrottle.
  97   // Note: in non-test cases, NavigationThrottles should not be added directly
  98   // but returned by the implementation of
  99   // ContentBrowserClient::CreateThrottlesForNavigation. This ensures proper
 100   // ordering of the throttles.
 101   virtual void RegisterThrottleForTesting(
 102       scoped_ptr<NavigationThrottle> navigation_throttle) = 0;
 103
 104   // Simulates the network request starting.
 105   virtual NavigationThrottle::ThrottleCheckResult
 106   CallWillStartRequestForTesting(bool is_post,
 107                                  const Referrer& sanitized_referrer,
 108                                  bool has_user_gesture,
 109                                  ui::PageTransition transition,
 110                                  bool is_external_protocol) = 0;
 111
 112   // Simulates the network request being redirected.
 113   virtual NavigationThrottle::ThrottleCheckResult
 114   CallWillRedirectRequestForTesting(const GURL& new_url,
 115                                     bool new_method_is_post,
 116                                     const GURL& new_referrer_url,
 117                                     bool new_is_external_protocol) = 0;
 118 };
 119
 120 }  // namespace content
 121
 122 #endif  // CONTENT_PUBLIC_BROWSER_NAVIGATION_HANDLE_H_