web_state_observer.h 7.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168
  1. // Copyright 2014 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. #ifndef IOS_WEB_PUBLIC_WEB_STATE_OBSERVER_H_
  5. #define IOS_WEB_PUBLIC_WEB_STATE_OBSERVER_H_
  6. #include <Foundation/Foundation.h>
  7. #include <stddef.h>
  8. #include <string>
  9. #include <vector>
  10. #include "base/observer_list_types.h"
  11. namespace web {
  12. struct FaviconURL;
  13. class NavigationContext;
  14. enum Permission : NSUInteger;
  15. class WebFrame;
  16. class WebState;
  17. enum class PageLoadCompletionStatus : bool { SUCCESS = 0, FAILURE = 1 };
  18. // An observer API implemented by classes which are interested in various page
  19. // load events from WebState.
  20. class WebStateObserver : public base::CheckedObserver {
  21. public:
  22. WebStateObserver(const WebStateObserver&) = delete;
  23. WebStateObserver& operator=(const WebStateObserver&) = delete;
  24. ~WebStateObserver() override;
  25. // These methods are invoked every time the WebState changes visibility.
  26. virtual void WasShown(WebState* web_state) {}
  27. virtual void WasHidden(WebState* web_state) {}
  28. // Called when a navigation started in the WebState for the main frame.
  29. // |navigation_context| is unique to a specific navigation. The same
  30. // NavigationContext will be provided on subsequent call to
  31. // DidFinishNavigation() when related to this navigation. Observers should
  32. // clear any references to |navigation_context| in DidFinishNavigation(), just
  33. // before it is destroyed.
  34. //
  35. // This is also fired by same-document navigations, such as fragment
  36. // navigations or pushState/replaceState, which will not result in a document
  37. // change. To filter these out, use NavigationContext::IsSameDocument().
  38. //
  39. // More than one navigation can be ongoing in the same frame at the same
  40. // time. Each will get its own NavigationContext.
  41. //
  42. // There is no guarantee that DidFinishNavigation() will be called for any
  43. // particular navigation before DidStartNavigation is called on the next.
  44. virtual void DidStartNavigation(WebState* web_state,
  45. NavigationContext* navigation_context) {}
  46. // Called when an in-progress main-frame navigation in |web_state| receives
  47. // a server redirect to a different URL. At the point where this is called,
  48. // |navigation_context|'s URL has already been updated, so calling GetUrl()
  49. // on |navigation_context| will return the redirect URL rather than the
  50. // original URL.
  51. virtual void DidRedirectNavigation(WebState* web_state,
  52. NavigationContext* navigation_context) {}
  53. // Called when a navigation finished in the WebState for the main frame. This
  54. // happens when a navigation is committed, aborted or replaced by a new one.
  55. // To know if the navigation has resulted in an error page, use
  56. // NavigationContext::GetError().
  57. //
  58. // If this is called because the navigation committed, then the document load
  59. // will still be ongoing in the WebState returned by |navigation_context|.
  60. // Use the document loads events such as DidStopLoading
  61. // and related methods to listen for continued events from this
  62. // WebState.
  63. //
  64. // This is also fired by same-document navigations, such as fragment
  65. // navigations or pushState/replaceState, which will not result in a document
  66. // change. To filter these out, use NavigationContext::IsSameDocument().
  67. //
  68. // |navigation_context| will be destroyed at the end of this call, so do not
  69. // keep a reference to it afterward.
  70. virtual void DidFinishNavigation(WebState* web_state,
  71. NavigationContext* navigation_context) {}
  72. // Called when the current WebState has started or stopped loading. This is
  73. // not correlated with the document load phase of the main frame, but rather
  74. // represents the load of the web page as a whole. Clients should present
  75. // network activity indicator UI to the user when DidStartLoading is called
  76. // and UI when DidStopLoading is called. DidStartLoading is a different event
  77. // than DidStartNavigation and clients should not assume that these two
  78. // callbacks always called in pair or in a specific order (same true for
  79. // DidFinishNavigation/DidFinishLoading). "Navigation" is about fetching the
  80. // new document content and committing it as a new document, and "Loading"
  81. // continues well after that. "Loading" callbacks are not called for fragment
  82. // change navigations, but called for other same-document navigations
  83. // (crbug.com/767092).
  84. virtual void DidStartLoading(WebState* web_state) {}
  85. virtual void DidStopLoading(WebState* web_state) {}
  86. // Called when the current page has finished the loading of the main frame
  87. // document (including same-document navigations). DidStopLoading relates to
  88. // the general loading state of the WebState, but PageLoaded is correlated
  89. // with the main frame document load phase. Unlike DidStopLoading, this
  90. // callback is not called when the load is aborted (WebState::Stop is called
  91. // or the load is rejected via WebStatePolicyDecider (both ShouldAllowRequest
  92. // or ShouldAllowResponse). If PageLoaded is called it is always called after
  93. // DidFinishNavigation.
  94. virtual void PageLoaded(WebState* web_state,
  95. PageLoadCompletionStatus load_completion_status) {}
  96. // Notifies the observer that the page has made some progress loading.
  97. // |progress| is a value between 0.0 (nothing loaded) to 1.0 (page fully
  98. // loaded).
  99. virtual void LoadProgressChanged(WebState* web_state, double progress) {}
  100. // Called when the canGoBack / canGoForward state of the window was changed.
  101. virtual void DidChangeBackForwardState(WebState* web_state) {}
  102. // Called when the title of the WebState is set.
  103. virtual void TitleWasSet(WebState* web_state) {}
  104. // Called when the visible security state of the page changes.
  105. virtual void DidChangeVisibleSecurityState(WebState* web_state) {}
  106. // Invoked when new favicon URL candidates are received.
  107. virtual void FaviconUrlUpdated(WebState* web_state,
  108. const std::vector<FaviconURL>& candidates) {}
  109. // Invoked when the state of a certain permission has changed.
  110. virtual void PermissionStateChanged(WebState* web_state,
  111. Permission permission)
  112. API_AVAILABLE(ios(15.0)) {}
  113. // Called when a frame was created or navigated to a new document.
  114. // Receivers can keep references to |web_frame| until
  115. // |WebFrameWillBecomeUnavailable| is called but must not assume that the
  116. // web Frame described by |web_frame| still exist.
  117. virtual void WebFrameDidBecomeAvailable(WebState* web_state,
  118. WebFrame* web_frame) {}
  119. // Called when a frame was deleted or navigated away from the document and
  120. // will be removed from the WebFramesManager.
  121. // Receivers of this callback should clear all references to
  122. // |web_frame|.
  123. virtual void WebFrameWillBecomeUnavailable(WebState* web_state,
  124. WebFrame* web_frame) {}
  125. // Called when the web process is terminated (usually by crashing, though
  126. // possibly by other means).
  127. virtual void RenderProcessGone(WebState* web_state) {}
  128. // Invoked when the WebState becomes realized (e.g. when it becomes fully
  129. // operational after being restored).
  130. virtual void WebStateRealized(WebState* web_state) {}
  131. // Invoked when the WebState is being destroyed. Gives subclasses a chance
  132. // to cleanup.
  133. virtual void WebStateDestroyed(WebState* web_state) {}
  134. protected:
  135. WebStateObserver();
  136. };
  137. } // namespace web
  138. #endif // IOS_WEB_PUBLIC_WEB_STATE_OBSERVER_H_