michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
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: /**
michael@0:  * The interface to nsISHentry. Each document or subframe in 
michael@0:  * Session History will have a nsISHEntry associated with it which will
michael@0:  * hold all information required to recreate the document from history
michael@0:  * 
michael@0:  */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsILayoutHistoryState;
michael@0: interface nsIContentViewer;
michael@0: interface nsIURI;
michael@0: interface nsIInputStream;
michael@0: interface nsIDocShellTreeItem;
michael@0: interface nsISupportsArray;
michael@0: interface nsIStructuredCloneContainer;
michael@0: interface nsIBFCacheEntry;
michael@0: 
michael@0: %{C++
michael@0: struct nsIntRect;
michael@0: class nsDocShellEditorData;
michael@0: class nsSHEntryShared;
michael@0: %}
michael@0: [ref] native nsIntRect(nsIntRect);
michael@0: [ptr] native nsDocShellEditorDataPtr(nsDocShellEditorData);
michael@0: [ptr] native nsSHEntryShared(nsSHEntryShared);
michael@0: 
michael@0: [scriptable, uuid(9eed7e92-1121-46f2-95e5-2f5c0dca46f0)]
michael@0: interface nsISHEntry : nsISupports
michael@0: {
michael@0:     /**
michael@0:      * A readonly property that returns the URI
michael@0:      * of the current entry. The object returned is
michael@0:      * of type nsIURI
michael@0:      */
michael@0:     readonly attribute nsIURI URI;
michael@0: 
michael@0:     /**
michael@0:      * A readonly property that returns the title
michael@0:      * of the current entry.  The object returned
michael@0:      * is a encoded string
michael@0:      */
michael@0:     readonly attribute wstring title;
michael@0: 
michael@0:     /**
michael@0:      * A readonly property that returns a boolean
michael@0:      * flag which indicates if the entry was created as a
michael@0:      * result of a subframe navigation. This flag will be
michael@0:      * 'false' when a frameset page is visited for
michael@0:      * the first time. This flag will be 'true' for all
michael@0:      * history entries created as a result of a subframe
michael@0:      * navigation.
michael@0:      */
michael@0:     readonly attribute boolean isSubFrame;
michael@0: 
michael@0:     /** URI for the document */
michael@0:     void setURI(in nsIURI aURI);
michael@0: 
michael@0:     /** Referrer URI */
michael@0:     attribute nsIURI referrerURI;
michael@0: 
michael@0:     /** Content viewer, for fast restoration of presentation */
michael@0:     attribute nsIContentViewer contentViewer;
michael@0: 
michael@0:     /** Whether the content viewer is marked "sticky" */
michael@0:     attribute boolean sticky;
michael@0: 
michael@0:     /** Saved state of the global window object */
michael@0:     attribute nsISupports windowState;
michael@0: 
michael@0:     /**
michael@0:      * Saved position and dimensions of the content viewer; we must adjust the
michael@0:      * root view's widget accordingly if this has changed when the presentation
michael@0:      * is restored.
michael@0:      */
michael@0:     [noscript] void getViewerBounds(in nsIntRect bounds);
michael@0:     [noscript] void setViewerBounds([const] in nsIntRect bounds);
michael@0: 
michael@0:     /**
michael@0:      * Saved child docshells corresponding to contentViewer.  The child shells
michael@0:      * are restored as children of the parent docshell, in this order, when the
michael@0:      * parent docshell restores a saved presentation.
michael@0:      */
michael@0: 
michael@0:     /** Append a child shell to the end of our list. */
michael@0:     void addChildShell(in nsIDocShellTreeItem shell);
michael@0: 
michael@0:     /**
michael@0:      * Get the child shell at |index|; returns null if |index| is out of bounds.
michael@0:      */
michael@0:     nsIDocShellTreeItem childShellAt(in long index);
michael@0: 
michael@0:     /**
michael@0:      * Clear the child shell list.
michael@0:      */
michael@0:     void clearChildShells();
michael@0: 
michael@0:     /** Saved refresh URI list for the content viewer */
michael@0:     attribute nsISupportsArray refreshURIList;
michael@0: 
michael@0:     /**
michael@0:      * Ensure that the cached presentation members are self-consistent.
michael@0:      * If either |contentViewer| or |windowState| are null, then all of the
michael@0:      * following members are cleared/reset:
michael@0:      *  contentViewer, sticky, windowState, viewerBounds, childShells,
michael@0:      *  refreshURIList.
michael@0:      */
michael@0:     void syncPresentationState();
michael@0: 
michael@0:     /** Title for the document */
michael@0:     void setTitle(in AString aTitle);
michael@0: 
michael@0:     /** Post Data for the document */
michael@0:     attribute nsIInputStream postData;
michael@0: 
michael@0:     /** LayoutHistoryState for scroll position and form values */
michael@0:     attribute nsILayoutHistoryState layoutHistoryState;
michael@0: 
michael@0:     /** parent of this entry */
michael@0:     attribute nsISHEntry parent;
michael@0: 
michael@0:     /**
michael@0:      * The loadType for this entry. This is typically loadHistory except
michael@0:      * when reload is pressed, it has the appropriate reload flag
michael@0:      */
michael@0:     attribute unsigned long loadType;
michael@0: 
michael@0:     /**
michael@0:      * An ID to help identify this entry from others during
michael@0:      * subframe navigation
michael@0:      */
michael@0:     attribute unsigned long ID;
michael@0: 
michael@0:     /** attribute to set and get the cache key for the entry */
michael@0:     attribute nsISupports cacheKey;
michael@0: 
michael@0:     /** attribute to indicate whether layoutHistoryState should be saved */
michael@0:     attribute boolean saveLayoutStateFlag;
michael@0: 
michael@0:     /** attribute to indicate whether the page is already expired in cache */
michael@0:     attribute boolean expirationStatus;
michael@0: 
michael@0:     /**
michael@0:      * attribute to indicate the content-type of the document that this
michael@0:      * is a session history entry for
michael@0:      */
michael@0:     attribute ACString contentType; 
michael@0: 
michael@0:     /**
michael@0:      * If we created this SHEntry via history.pushState or modified it via
michael@0:      * history.replaceState, and if we changed the SHEntry's URI via the
michael@0:      * push/replaceState call, and if the SHEntry's new URI differs from its
michael@0:      * old URI by more than just the hash, then we set this field to true.
michael@0:      *
michael@0:      * Additionally, if this SHEntry was created by calling pushState from a
michael@0:      * SHEntry whose URI was modified, this SHEntry's URIWasModified field is
michael@0:      * true.
michael@0:      *
michael@0:      */
michael@0:     attribute boolean URIWasModified;
michael@0:  
michael@0:     /** Set/Get scrollers' positon in anchored pages */
michael@0:     void setScrollPosition(in long x, in long y);
michael@0:     void getScrollPosition(out long x, out long y);
michael@0: 
michael@0:     /** Additional ways to create an entry */
michael@0:     [noscript] void create(in nsIURI URI, in AString title,
michael@0:                            in nsIInputStream inputStream,
michael@0:                            in nsILayoutHistoryState layoutHistoryState,
michael@0:                            in nsISupports cacheKey, in ACString contentType,
michael@0:                            in nsISupports owner,
michael@0:                            in unsigned long long docshellID,
michael@0:                            in boolean dynamicCreation);
michael@0: 
michael@0:     nsISHEntry clone();
michael@0: 
michael@0:     /** Attribute that indicates if this entry is for a subframe navigation */
michael@0:     void setIsSubFrame(in boolean aFlag);
michael@0: 
michael@0:     /** Return any content viewer present in or below this node in the
michael@0:         nsSHEntry tree.  This will differ from contentViewer in the case
michael@0:         where a child nsSHEntry has the content viewer for this tree. */
michael@0:     nsIContentViewer getAnyContentViewer(out nsISHEntry ownerEntry);
michael@0: 
michael@0:     /**
michael@0:      * Get the owner, if any, that was associated with the channel
michael@0:      * that the document that was loaded to create this history entry
michael@0:      * came from.
michael@0:      */
michael@0:     attribute nsISupports owner;
michael@0: 
michael@0:     /**
michael@0:      * Get/set data associated with this history state via a pushState() call,
michael@0:      * serialized using structured clone.
michael@0:      **/
michael@0:     attribute nsIStructuredCloneContainer stateData;
michael@0: 
michael@0:     /**
michael@0:      * Gets the owning pointer to the editor data assosicated with
michael@0:      * this shistory entry. This forgets its pointer, so free it when
michael@0:      * you're done.
michael@0:      */
michael@0:     [noscript, notxpcom] nsDocShellEditorDataPtr forgetEditorData();
michael@0: 
michael@0:     /**
michael@0:      * Sets the owning pointer to the editor data assosicated with
michael@0:      * this shistory entry. Unless forgetEditorData() is called, this
michael@0:      * shentry will destroy the editor data when it's destroyed.
michael@0:      */
michael@0:     [noscript, notxpcom] void setEditorData(in nsDocShellEditorDataPtr aData);
michael@0: 
michael@0:     /** Returns true if this shistory entry is storing a detached editor. */
michael@0:     [noscript, notxpcom] boolean hasDetachedEditor();
michael@0: 
michael@0:     /**
michael@0:      * Returns true if the related docshell was added because of
michael@0:      * dynamic addition of an iframe/frame.
michael@0:      */
michael@0:     boolean isDynamicallyAdded();
michael@0: 
michael@0:     /**
michael@0:      * Returns true if any of the child entries returns true
michael@0:      * when isDynamicallyAdded is called on it.
michael@0:      */
michael@0:     boolean hasDynamicallyAddedChild();
michael@0: 
michael@0:     /**
michael@0:      * The history ID of the docshell.
michael@0:      */
michael@0:     attribute unsigned long long docshellID;
michael@0: 
michael@0:     readonly attribute nsIBFCacheEntry BFCacheEntry;
michael@0: 
michael@0:     /**
michael@0:      * Does this SHEntry point to the given BFCache entry?  If so, evicting
michael@0:      * the BFCache entry will evict the SHEntry, since the two entries
michael@0:      * correspond to the same document.
michael@0:      */
michael@0:     [notxpcom, noscript]
michael@0:     boolean hasBFCacheEntry(in nsIBFCacheEntry aEntry);
michael@0: 
michael@0:     /**
michael@0:      * Adopt aEntry's BFCacheEntry, so now both this and aEntry point to
michael@0:      * aEntry's BFCacheEntry.
michael@0:      */
michael@0:     void adoptBFCacheEntry(in nsISHEntry aEntry);
michael@0: 
michael@0:     /**
michael@0:      * Create a new BFCache entry and drop our reference to our old one.  This
michael@0:      * call unlinks this SHEntry from any other SHEntries for its document.
michael@0:      */
michael@0:     void abandonBFCacheEntry();
michael@0: 
michael@0:     /**
michael@0:      * Does this SHEntry correspond to the same document as aEntry?  This is
michael@0:      * true iff the two SHEntries have the same BFCacheEntry.  So in
michael@0:      * particular, sharesDocumentWith(aEntry) is guaranteed to return true if
michael@0:      * it's preceeded by a call to adoptBFCacheEntry(aEntry).
michael@0:      */
michael@0:     boolean sharesDocumentWith(in nsISHEntry aEntry);
michael@0: 
michael@0:     /**
michael@0:      * True if this SHEntry corresponds to a document created by a srcdoc iframe.
michael@0:      * Set when a value is assigned to  srcdocData.
michael@0:      */
michael@0:     readonly attribute boolean isSrcdocEntry;
michael@0: 
michael@0:     /**
michael@0:      * Contents of the srcdoc attribute in a srcdoc iframe to be loaded instead
michael@0:      * of the URI.  Similar to a Data URI, this information is needed to
michael@0:      * recreate the document at a later stage.
michael@0:      * Setting this sets isSrcdocEntry to true
michael@0:      */
michael@0:     attribute AString srcdocData;
michael@0: 
michael@0:     /**
michael@0:      * When isSrcdocEntry is true, this contains the baseURI of the srcdoc
michael@0:      * document for use in situations where it cannot otherwise be determined,
michael@0:      * for example with view-source.
michael@0:      */
michael@0:     attribute nsIURI baseURI;
michael@0: };
michael@0: 
michael@0: [scriptable, uuid(bb66ac35-253b-471f-a317-3ece940f04c5)]
michael@0: interface nsISHEntryInternal : nsISupports
michael@0: {
michael@0:     [notxpcom] void RemoveFromBFCacheAsync();
michael@0:     [notxpcom] void RemoveFromBFCacheSync();
michael@0: 
michael@0:     /**
michael@0:      * A number that is assigned by the sHistory when the entry is activated
michael@0:      */
michael@0:     attribute unsigned long lastTouched;
michael@0: 
michael@0:     /**
michael@0:      * Some state, particularly that related to the back/forward cache, is
michael@0:      * shared between SHEntries which correspond to the same document.  This
michael@0:      * method gets a pointer to that shared state.
michael@0:      *
michael@0:      * This shared state is the SHEntry's BFCacheEntry.  So
michael@0:      * hasBFCacheEntry(getSharedState()) is guaranteed to return true.
michael@0:      */
michael@0:     [noscript, notxpcom]
michael@0:     nsSHEntryShared getSharedState();
michael@0: };
michael@0: 
michael@0: %{ C++
michael@0: // {BFD1A791-AD9F-11d3-BDC7-0050040A9B44}
michael@0: #define NS_SHENTRY_CID \
michael@0: {0xbfd1a791, 0xad9f, 0x11d3, {0xbd, 0xc7, 0x0, 0x50, 0x4, 0xa, 0x9b, 0x44}}
michael@0: 
michael@0: #define NS_SHENTRY_CONTRACTID \
michael@0:     "@mozilla.org/browser/session-history-entry;1"
michael@0: 
michael@0: %}
michael@0: