docshell/base/IHistory.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  * vim: set ts=4 sw=4 et 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
  12 class nsIURI;
  13 class nsString;
  14
  15 namespace mozilla {
  16
  17     namespace dom {
  18         class Link;
  19     }
  20
  21 // 0057c9d3-b98e-4933-bdc5-0275d06705e1
  22 #define IHISTORY_IID \
  23   {0x0057c9d3, 0xb98e, 0x4933, {0xbd, 0xc5, 0x02, 0x75, 0xd0, 0x67, 0x05, 0xe1}}
  24
  25 class IHistory : public nsISupports
  26 {
  27 public:
  28     NS_DECLARE_STATIC_IID_ACCESSOR(IHISTORY_IID)
  29
  30     /**
  31      * Registers the Link for notifications about the visited-ness of aURI.
  32      * Consumers should assume that the URI is unvisited after calling this, and
  33      * they will be notified if that state (unvisited) changes by having
  34      * SetLinkState called on themselves.  This function is guaranteed to run to
  35      * completion before aLink is notified.  After the node is notified, it will
  36      * be unregistered.
  37      *
  38      * @note SetLinkState must not call RegisterVisitedCallback or
  39      *       UnregisterVisitedCallback.
  40      *
  41      * @pre aURI must not be null.
  42      * @pre aLink may be null only in the parent (chrome) process.
  43      *
  44      * @param aURI
  45      *        The URI to check.
  46      * @param aLink
  47      *        The link to update whenever the history status changes.  The
  48      *        implementation will only hold onto a raw pointer, so if this
  49      *        object should be destroyed, be sure to call
  50      *        UnregisterVistedCallback first.
  51      */
  52     NS_IMETHOD RegisterVisitedCallback(nsIURI *aURI, dom::Link *aLink) = 0;
  53
  54     /**
  55      * Unregisters a previously registered Link object.  This must be called
  56      * before destroying the registered object.
  57      *
  58      * @pre aURI must not be null.
  59      * @pre aLink must not be null.
  60      *
  61      * @param aURI
  62      *        The URI that aLink was registered for.
  63      * @param aLink
  64      *        The link object to unregister for aURI.
  65      */
  66     NS_IMETHOD UnregisterVisitedCallback(nsIURI *aURI, dom::Link *aLink) = 0;
  67
  68     enum VisitFlags {
  69         /**
  70          * Indicates whether the URI was loaded in a top-level window.
  71          */
  72         TOP_LEVEL = 1 << 0,
  73         /**
  74          * Indicates whether the URI was loaded as part of a permanent redirect.
  75          */
  76         REDIRECT_PERMANENT = 1 << 1,
  77         /**
  78          * Indicates whether the URI was loaded as part of a temporary redirect.
  79          */
  80         REDIRECT_TEMPORARY = 1 << 2,
  81         /**
  82          * Indicates the URI is redirecting  (Response code 3xx).
  83          */
  84         REDIRECT_SOURCE = 1 << 3,
  85         /**
  86          * Indicates the URI caused an error that is unlikely fixable by a
  87          * retry, like a not found or unfetchable page.
  88          */
  89         UNRECOVERABLE_ERROR = 1 << 4
  90     };
  91
  92     /**
  93      * Adds a history visit for the URI.
  94      *
  95      * @pre aURI must not be null.
  96      *
  97      * @param aURI
  98      *        The URI of the page being visited.
  99      * @param aLastVisitedURI
 100      *        The URI of the last visit in the chain.
 101      * @param aFlags
 102      *        The VisitFlags describing this visit.
 103      */
 104     NS_IMETHOD VisitURI(
 105         nsIURI *aURI,
 106         nsIURI *aLastVisitedURI,
 107         uint32_t aFlags
 108     ) = 0;
 109
 110     /**
 111      * Set the title of the URI.
 112      *
 113      * @pre aURI must not be null.
 114      *
 115      * @param aURI
 116      *        The URI to set the title for.
 117      * @param aTitle
 118      *        The title string.
 119      */
 120     NS_IMETHOD SetURITitle(nsIURI* aURI, const nsAString& aTitle) = 0;
 121
 122     /**
 123      * Notifies about the visited status of a given URI.
 124      *
 125      * @param aURI
 126      *        The URI to notify about.
 127      */
 128     NS_IMETHOD NotifyVisited(nsIURI* aURI) = 0;
 129 };
 130
 131 NS_DEFINE_STATIC_IID_ACCESSOR(IHistory, IHISTORY_IID)
 132
 133 #define NS_DECL_IHISTORY \
 134     NS_IMETHOD RegisterVisitedCallback(nsIURI *aURI, \
 135                                        mozilla::dom::Link *aContent); \
 136     NS_IMETHOD UnregisterVisitedCallback(nsIURI *aURI, \
 137                                          mozilla::dom::Link *aContent); \
 138     NS_IMETHOD VisitURI(nsIURI *aURI, \
 139                         nsIURI *aLastVisitedURI, \
 140                         uint32_t aFlags); \
 141     NS_IMETHOD SetURITitle(nsIURI* aURI, const nsAString& aTitle); \
 142     NS_IMETHOD NotifyVisited(nsIURI* aURI);
 143
 144 } // namespace mozilla
 145
 146 #endif // mozilla_IHistory_h_