michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
michael@0:  * vim: set ts=4 sw=4 et tw=80:
michael@0:  * This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #ifndef mozilla_IHistory_h_
michael@0: #define mozilla_IHistory_h_
michael@0: 
michael@0: #include "nsISupports.h"
michael@0: 
michael@0: class nsIURI;
michael@0: class nsString;
michael@0: 
michael@0: namespace mozilla {
michael@0: 
michael@0:     namespace dom {
michael@0:         class Link;
michael@0:     }
michael@0: 
michael@0: // 0057c9d3-b98e-4933-bdc5-0275d06705e1
michael@0: #define IHISTORY_IID \
michael@0:   {0x0057c9d3, 0xb98e, 0x4933, {0xbd, 0xc5, 0x02, 0x75, 0xd0, 0x67, 0x05, 0xe1}}
michael@0: 
michael@0: class IHistory : public nsISupports
michael@0: {
michael@0: public:
michael@0:     NS_DECLARE_STATIC_IID_ACCESSOR(IHISTORY_IID)
michael@0: 
michael@0:     /**
michael@0:      * Registers the Link for notifications about the visited-ness of aURI.
michael@0:      * Consumers should assume that the URI is unvisited after calling this, and
michael@0:      * they will be notified if that state (unvisited) changes by having
michael@0:      * SetLinkState called on themselves.  This function is guaranteed to run to
michael@0:      * completion before aLink is notified.  After the node is notified, it will
michael@0:      * be unregistered.
michael@0:      *
michael@0:      * @note SetLinkState must not call RegisterVisitedCallback or
michael@0:      *       UnregisterVisitedCallback.
michael@0:      *
michael@0:      * @pre aURI must not be null.
michael@0:      * @pre aLink may be null only in the parent (chrome) process.
michael@0:      *
michael@0:      * @param aURI
michael@0:      *        The URI to check.
michael@0:      * @param aLink
michael@0:      *        The link to update whenever the history status changes.  The
michael@0:      *        implementation will only hold onto a raw pointer, so if this
michael@0:      *        object should be destroyed, be sure to call
michael@0:      *        UnregisterVistedCallback first.
michael@0:      */
michael@0:     NS_IMETHOD RegisterVisitedCallback(nsIURI *aURI, dom::Link *aLink) = 0;
michael@0: 
michael@0:     /**
michael@0:      * Unregisters a previously registered Link object.  This must be called
michael@0:      * before destroying the registered object.
michael@0:      *
michael@0:      * @pre aURI must not be null.
michael@0:      * @pre aLink must not be null.
michael@0:      *
michael@0:      * @param aURI
michael@0:      *        The URI that aLink was registered for.
michael@0:      * @param aLink
michael@0:      *        The link object to unregister for aURI.
michael@0:      */
michael@0:     NS_IMETHOD UnregisterVisitedCallback(nsIURI *aURI, dom::Link *aLink) = 0;
michael@0: 
michael@0:     enum VisitFlags {
michael@0:         /**
michael@0:          * Indicates whether the URI was loaded in a top-level window.
michael@0:          */
michael@0:         TOP_LEVEL = 1 << 0,
michael@0:         /**
michael@0:          * Indicates whether the URI was loaded as part of a permanent redirect.
michael@0:          */
michael@0:         REDIRECT_PERMANENT = 1 << 1,
michael@0:         /**
michael@0:          * Indicates whether the URI was loaded as part of a temporary redirect.
michael@0:          */
michael@0:         REDIRECT_TEMPORARY = 1 << 2,
michael@0:         /**
michael@0:          * Indicates the URI is redirecting  (Response code 3xx).
michael@0:          */
michael@0:         REDIRECT_SOURCE = 1 << 3,
michael@0:         /**
michael@0:          * Indicates the URI caused an error that is unlikely fixable by a
michael@0:          * retry, like a not found or unfetchable page.
michael@0:          */
michael@0:         UNRECOVERABLE_ERROR = 1 << 4
michael@0:     };
michael@0: 
michael@0:     /**
michael@0:      * Adds a history visit for the URI.
michael@0:      *
michael@0:      * @pre aURI must not be null.
michael@0:      *
michael@0:      * @param aURI
michael@0:      *        The URI of the page being visited.
michael@0:      * @param aLastVisitedURI
michael@0:      *        The URI of the last visit in the chain.
michael@0:      * @param aFlags
michael@0:      *        The VisitFlags describing this visit.
michael@0:      */
michael@0:     NS_IMETHOD VisitURI(
michael@0:         nsIURI *aURI,
michael@0:         nsIURI *aLastVisitedURI,
michael@0:         uint32_t aFlags
michael@0:     ) = 0;
michael@0: 
michael@0:     /**
michael@0:      * Set the title of the URI.
michael@0:      *
michael@0:      * @pre aURI must not be null.
michael@0:      *
michael@0:      * @param aURI
michael@0:      *        The URI to set the title for.
michael@0:      * @param aTitle
michael@0:      *        The title string.
michael@0:      */
michael@0:     NS_IMETHOD SetURITitle(nsIURI* aURI, const nsAString& aTitle) = 0;
michael@0: 
michael@0:     /**
michael@0:      * Notifies about the visited status of a given URI.
michael@0:      *
michael@0:      * @param aURI
michael@0:      *        The URI to notify about.
michael@0:      */
michael@0:     NS_IMETHOD NotifyVisited(nsIURI* aURI) = 0;
michael@0: };
michael@0: 
michael@0: NS_DEFINE_STATIC_IID_ACCESSOR(IHistory, IHISTORY_IID)
michael@0: 
michael@0: #define NS_DECL_IHISTORY \
michael@0:     NS_IMETHOD RegisterVisitedCallback(nsIURI *aURI, \
michael@0:                                        mozilla::dom::Link *aContent); \
michael@0:     NS_IMETHOD UnregisterVisitedCallback(nsIURI *aURI, \
michael@0:                                          mozilla::dom::Link *aContent); \
michael@0:     NS_IMETHOD VisitURI(nsIURI *aURI, \
michael@0:                         nsIURI *aLastVisitedURI, \
michael@0:                         uint32_t aFlags); \
michael@0:     NS_IMETHOD SetURITitle(nsIURI* aURI, const nsAString& aTitle); \
michael@0:     NS_IMETHOD NotifyVisited(nsIURI* aURI);
michael@0: 
michael@0: } // namespace mozilla
michael@0: 
michael@0: #endif // mozilla_IHistory_h_