The Tor Browser / file revision

 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */

 /* This Source Code Form is subject to the terms of the Mozilla Public

  * License, v. 2.0. If a copy of the MPL was not distributed with this

  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

 /**

  * The interface to nsISHentry. Each document or subframe in 

  * Session History will have a nsISHEntry associated with it which will

  * hold all information required to recreate the document from history

  * 

  */

 #include "nsISupports.idl"

 interface nsILayoutHistoryState;

 interface nsIContentViewer;

 interface nsIURI;

 interface nsIInputStream;

 interface nsIDocShellTreeItem;

 interface nsISupportsArray;

 interface nsIStructuredCloneContainer;

 interface nsIBFCacheEntry;

 %{C++

 struct nsIntRect;

 class nsDocShellEditorData;

 class nsSHEntryShared;

 %}

 [ref] native nsIntRect(nsIntRect);

 [ptr] native nsDocShellEditorDataPtr(nsDocShellEditorData);

 [ptr] native nsSHEntryShared(nsSHEntryShared);

 [scriptable, uuid(9eed7e92-1121-46f2-95e5-2f5c0dca46f0)]

 interface nsISHEntry : nsISupports

 {

     /**

      * A readonly property that returns the URI

      * of the current entry. The object returned is

      * of type nsIURI

      */

     readonly attribute nsIURI URI;

     /**

      * A readonly property that returns the title

      * of the current entry.  The object returned

      * is a encoded string

      */

     readonly attribute wstring title;

     /**

      * A readonly property that returns a boolean

      * flag which indicates if the entry was created as a

      * result of a subframe navigation. This flag will be

      * 'false' when a frameset page is visited for

      * the first time. This flag will be 'true' for all

      * history entries created as a result of a subframe

      * navigation.

      */

     readonly attribute boolean isSubFrame;

     /** URI for the document */

     void setURI(in nsIURI aURI);

     /** Referrer URI */

     attribute nsIURI referrerURI;

     /** Content viewer, for fast restoration of presentation */

     attribute nsIContentViewer contentViewer;

     /** Whether the content viewer is marked "sticky" */

     attribute boolean sticky;

     /** Saved state of the global window object */

     attribute nsISupports windowState;

     /**

      * Saved position and dimensions of the content viewer; we must adjust the

      * root view's widget accordingly if this has changed when the presentation

      * is restored.

      */

     [noscript] void getViewerBounds(in nsIntRect bounds);

     [noscript] void setViewerBounds([const] in nsIntRect bounds);

     /**

      * Saved child docshells corresponding to contentViewer.  The child shells

      * are restored as children of the parent docshell, in this order, when the

      * parent docshell restores a saved presentation.

      */

     /** Append a child shell to the end of our list. */

     void addChildShell(in nsIDocShellTreeItem shell);

     /**

      * Get the child shell at |index|; returns null if |index| is out of bounds.

      */

     nsIDocShellTreeItem childShellAt(in long index);

     /**

      * Clear the child shell list.

      */

     void clearChildShells();

     /** Saved refresh URI list for the content viewer */

     attribute nsISupportsArray refreshURIList;

     /**

      * Ensure that the cached presentation members are self-consistent.

      * If either |contentViewer| or |windowState| are null, then all of the

      * following members are cleared/reset:

      *  contentViewer, sticky, windowState, viewerBounds, childShells,

      *  refreshURIList.

      */

     void syncPresentationState();

     /** Title for the document */

     void setTitle(in AString aTitle);

     /** Post Data for the document */

     attribute nsIInputStream postData;

     /** LayoutHistoryState for scroll position and form values */

     attribute nsILayoutHistoryState layoutHistoryState;

     /** parent of this entry */

     attribute nsISHEntry parent;

     /**

      * The loadType for this entry. This is typically loadHistory except

      * when reload is pressed, it has the appropriate reload flag

      */

     attribute unsigned long loadType;

     /**

      * An ID to help identify this entry from others during

      * subframe navigation

      */

     attribute unsigned long ID;

     /** attribute to set and get the cache key for the entry */

     attribute nsISupports cacheKey;

     /** attribute to indicate whether layoutHistoryState should be saved */

     attribute boolean saveLayoutStateFlag;

     /** attribute to indicate whether the page is already expired in cache */

     attribute boolean expirationStatus;

     /**

      * attribute to indicate the content-type of the document that this

      * is a session history entry for

      */

     attribute ACString contentType; 

     /**

      * If we created this SHEntry via history.pushState or modified it via

      * history.replaceState, and if we changed the SHEntry's URI via the

      * push/replaceState call, and if the SHEntry's new URI differs from its

      * old URI by more than just the hash, then we set this field to true.

      *

      * Additionally, if this SHEntry was created by calling pushState from a

      * SHEntry whose URI was modified, this SHEntry's URIWasModified field is

      * true.

      *

      */

     attribute boolean URIWasModified;

     /** Set/Get scrollers' positon in anchored pages */

     void setScrollPosition(in long x, in long y);

     void getScrollPosition(out long x, out long y);

     /** Additional ways to create an entry */

     [noscript] void create(in nsIURI URI, in AString title,

                            in nsIInputStream inputStream,

                            in nsILayoutHistoryState layoutHistoryState,

                            in nsISupports cacheKey, in ACString contentType,

                            in nsISupports owner,

                            in unsigned long long docshellID,

                            in boolean dynamicCreation);

     nsISHEntry clone();

     /** Attribute that indicates if this entry is for a subframe navigation */

     void setIsSubFrame(in boolean aFlag);

     /** Return any content viewer present in or below this node in the

         nsSHEntry tree.  This will differ from contentViewer in the case

         where a child nsSHEntry has the content viewer for this tree. */

     nsIContentViewer getAnyContentViewer(out nsISHEntry ownerEntry);

     /**

      * Get the owner, if any, that was associated with the channel

      * that the document that was loaded to create this history entry

      * came from.

      */

     attribute nsISupports owner;

     /**

      * Get/set data associated with this history state via a pushState() call,

      * serialized using structured clone.

      **/

     attribute nsIStructuredCloneContainer stateData;

     /**

      * Gets the owning pointer to the editor data assosicated with

      * this shistory entry. This forgets its pointer, so free it when

      * you're done.

      */

     [noscript, notxpcom] nsDocShellEditorDataPtr forgetEditorData();

     /**

      * Sets the owning pointer to the editor data assosicated with

      * this shistory entry. Unless forgetEditorData() is called, this

      * shentry will destroy the editor data when it's destroyed.

      */

     [noscript, notxpcom] void setEditorData(in nsDocShellEditorDataPtr aData);

     /** Returns true if this shistory entry is storing a detached editor. */

     [noscript, notxpcom] boolean hasDetachedEditor();

     /**

      * Returns true if the related docshell was added because of

      * dynamic addition of an iframe/frame.

      */

     boolean isDynamicallyAdded();

     /**

      * Returns true if any of the child entries returns true

      * when isDynamicallyAdded is called on it.

      */

     boolean hasDynamicallyAddedChild();

     /**

      * The history ID of the docshell.

      */

     attribute unsigned long long docshellID;

     readonly attribute nsIBFCacheEntry BFCacheEntry;

     /**

      * Does this SHEntry point to the given BFCache entry?  If so, evicting

      * the BFCache entry will evict the SHEntry, since the two entries

      * correspond to the same document.

      */

     [notxpcom, noscript]

     boolean hasBFCacheEntry(in nsIBFCacheEntry aEntry);

     /**

      * Adopt aEntry's BFCacheEntry, so now both this and aEntry point to

      * aEntry's BFCacheEntry.

      */

     void adoptBFCacheEntry(in nsISHEntry aEntry);

     /**

      * Create a new BFCache entry and drop our reference to our old one.  This

      * call unlinks this SHEntry from any other SHEntries for its document.

      */

     void abandonBFCacheEntry();

     /**

      * Does this SHEntry correspond to the same document as aEntry?  This is

      * true iff the two SHEntries have the same BFCacheEntry.  So in

      * particular, sharesDocumentWith(aEntry) is guaranteed to return true if

      * it's preceeded by a call to adoptBFCacheEntry(aEntry).

      */

     boolean sharesDocumentWith(in nsISHEntry aEntry);

     /**

      * True if this SHEntry corresponds to a document created by a srcdoc iframe.

      * Set when a value is assigned to  srcdocData.

      */

     readonly attribute boolean isSrcdocEntry;

     /**

      * Contents of the srcdoc attribute in a srcdoc iframe to be loaded instead

      * of the URI.  Similar to a Data URI, this information is needed to

      * recreate the document at a later stage.

      * Setting this sets isSrcdocEntry to true

      */

     attribute AString srcdocData;

     /**

      * When isSrcdocEntry is true, this contains the baseURI of the srcdoc

      * document for use in situations where it cannot otherwise be determined,

      * for example with view-source.

      */

     attribute nsIURI baseURI;

 };

 [scriptable, uuid(bb66ac35-253b-471f-a317-3ece940f04c5)]

 interface nsISHEntryInternal : nsISupports

 {

     [notxpcom] void RemoveFromBFCacheAsync();

     [notxpcom] void RemoveFromBFCacheSync();

     /**

      * A number that is assigned by the sHistory when the entry is activated

      */

     attribute unsigned long lastTouched;

     /**

      * Some state, particularly that related to the back/forward cache, is

      * shared between SHEntries which correspond to the same document.  This

      * method gets a pointer to that shared state.

      *

      * This shared state is the SHEntry's BFCacheEntry.  So

      * hasBFCacheEntry(getSharedState()) is guaranteed to return true.

      */

     [noscript, notxpcom]

     nsSHEntryShared getSharedState();

 };

 %{ C++

 // {BFD1A791-AD9F-11d3-BDC7-0050040A9B44}

 #define NS_SHENTRY_CID \

 {0xbfd1a791, 0xad9f, 0x11d3, {0xbd, 0xc7, 0x0, 0x50, 0x4, 0xa, 0x9b, 0x44}}

 #define NS_SHENTRY_CONTRACTID \

     "@mozilla.org/browser/session-history-entry;1"

 %}