docshell/base/IHistory.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef mozilla_IHistory_h_
   8 #define mozilla_IHistory_h_
   9
  10 #include "nsISupports.h"
  11 #include "nsURIHashKey.h"
  12 #include "nsTHashSet.h"
  13 #include "nsTObserverArray.h"
  14
  15 class nsIURI;
  16 class nsIWidget;
  17
  18 namespace mozilla {
  19
  20 namespace dom {
  21 class ContentParent;
  22 class Document;
  23 class Link;
  24 }  // namespace dom
  25
  26 // 0057c9d3-b98e-4933-bdc5-0275d06705e1
  27 #define IHISTORY_IID                                 \
  28   {                                                  \
  29     0x0057c9d3, 0xb98e, 0x4933, {                    \
  30       0xbd, 0xc5, 0x02, 0x75, 0xd0, 0x67, 0x05, 0xe1 \
  31     }                                                \
  32   }
  33
  34 class IHistory : public nsISupports {
  35  public:
  36   NS_DECLARE_STATIC_IID_ACCESSOR(IHISTORY_IID)
  37
  38   using ContentParentSet = nsTHashSet<RefPtr<dom::ContentParent>>;
  39
  40   /**
  41    * Registers the Link for notifications about the visited-ness of aURI.
  42    * Consumers should assume that the URI is unvisited after calling this, and
  43    * they will be notified if that state (unvisited) changes by having
  44    * VisitedQueryFinished called on themselves. Note that it may call
  45    * synchronously if the answer is already known.
  46    *
  47    * @note VisitedQueryFinished must not call RegisterVisitedCallback or
  48    *       UnregisterVisitedCallback.
  49    *
  50    * @pre aURI must not be null.
  51    * @pre aLink may be null only in the parent (chrome) process.
  52    *
  53    * @param aURI
  54    *        The URI to check.
  55    * @param aLink
  56    *        The link to update whenever the history status changes.  The
  57    *        implementation will only hold onto a raw pointer, so if this
  58    *        object should be destroyed, be sure to call
  59    *        UnregisterVistedCallback first.
  60    */
  61   virtual void RegisterVisitedCallback(nsIURI* aURI, dom::Link* aLink) = 0;
  62
  63   /**
  64    * Schedules a single visited query from a given child process.
  65    *
  66    * @param aURI the URI to query.
  67    * @param ContentParent the process interested in knowing about the visited
  68    *                      state of this URI.
  69    */
  70   virtual void ScheduleVisitedQuery(nsIURI* aURI, dom::ContentParent*) = 0;
  71
  72   /**
  73    * Unregisters a previously registered Link object.  This must be called
  74    * before destroying the registered object, and asserts when misused.
  75    *
  76    * @pre aURI must not be null.
  77    * @pre aLink must not be null.
  78    *
  79    * @param aURI
  80    *        The URI that aLink was registered for.
  81    * @param aLink
  82    *        The link object to unregister for aURI.
  83    */
  84   virtual void UnregisterVisitedCallback(nsIURI* aURI, dom::Link* aLink) = 0;
  85
  86   enum class VisitedStatus : uint8_t {
  87     Unknown,
  88     Visited,
  89     Unvisited,
  90   };
  91
  92   /**
  93    * Notifies about the visited status of a given URI. The visited status cannot
  94    * be unknown, otherwise there's no point in notifying of anything.
  95    *
  96    * @param ContentParentSet a set of content processes that are interested on
  97    *                         this change. If null, it is broadcasted to all
  98    *                         child processes.
  99    */
 100   virtual void NotifyVisited(nsIURI*, VisitedStatus,
 101                              const ContentParentSet* = nullptr) = 0;
 102
 103   enum VisitFlags {
 104     /**
 105      * Indicates whether the URI was loaded in a top-level window.
 106      */
 107     TOP_LEVEL = 1 << 0,
 108     /**
 109      * Indicates whether the URI is the target of a permanent redirect.
 110      */
 111     REDIRECT_PERMANENT = 1 << 1,
 112     /**
 113      * Indicates whether the URI is the target of a temporary redirect.
 114      */
 115     REDIRECT_TEMPORARY = 1 << 2,
 116     /**
 117      * Indicates the URI will redirect  (Response code 3xx).
 118      */
 119     REDIRECT_SOURCE = 1 << 3,
 120     /**
 121      * Indicates the URI caused an error that is unlikely fixable by a
 122      * retry, like a not found or unfetchable page.
 123      */
 124     UNRECOVERABLE_ERROR = 1 << 4,
 125     /**
 126      * If REDIRECT_SOURCE is set, this indicates that the redirect is permanent.
 127      * Note this differs from REDIRECT_PERMANENT because that one refers to how
 128      * we reached the URI, while this is used when the URI itself redirects.
 129      */
 130     REDIRECT_SOURCE_PERMANENT = 1 << 5
 131   };
 132
 133   /**
 134    * Adds a history visit for the URI.
 135    *
 136    * @pre aURI must not be null.
 137    *
 138    * @param aWidget
 139    *        The widget for the DocShell.
 140    * @param aURI
 141    *        The URI of the page being visited.
 142    * @param aLastVisitedURI
 143    *        The URI of the last visit in the chain.
 144    * @param aFlags
 145    *        The VisitFlags describing this visit.
 146    * @param aBrowserId
 147    *        The id of browser used for this visit.
 148    */
 149   NS_IMETHOD VisitURI(nsIWidget* aWidget, nsIURI* aURI, nsIURI* aLastVisitedURI,
 150                       uint32_t aFlags, uint64_t aBrowserId) = 0;
 151
 152   /**
 153    * Set the title of the URI.
 154    *
 155    * @pre aURI must not be null.
 156    *
 157    * @param aURI
 158    *        The URI to set the title for.
 159    * @param aTitle
 160    *        The title string.
 161    */
 162   NS_IMETHOD SetURITitle(nsIURI* aURI, const nsAString& aTitle) = 0;
 163 };
 164
 165 NS_DEFINE_STATIC_IID_ACCESSOR(IHistory, IHISTORY_IID)
 166
 167 }  // namespace mozilla
 168
 169 #endif  // mozilla_IHistory_h_