"Fossies" - the Fresh Open Source Software Archive

Member "firefox-69.0.1/docshell/shistory/nsISHEntry.idl" (17 Sep 2019, 13825 Bytes) of package /linux/www/firefox-69.0.1.source.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) IDL source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "nsISHEntry.idl": 68.0.2_vs_69.0.

    1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
    2 /* This Source Code Form is subject to the terms of the Mozilla Public
    3  * License, v. 2.0. If a copy of the MPL was not distributed with this
    4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
    5 
    6 /**
    7  * The interface to nsISHentry. Each document or subframe in
    8  * Session History will have a nsISHEntry associated with it which will
    9  * hold all information required to recreate the document from history
   10  */
   11 
   12 #include "nsISupports.idl"
   13 
   14 interface nsIContentSecurityPolicy;
   15 interface nsIMutableArray;
   16 interface nsILayoutHistoryState;
   17 interface nsIContentViewer;
   18 interface nsIURI;
   19 interface nsIInputStream;
   20 interface nsIDocShellTreeItem;
   21 interface nsIStructuredCloneContainer;
   22 interface nsIBFCacheEntry;
   23 interface nsIPrincipal;
   24 interface nsISHistory;
   25 interface nsIReferrerInfo;
   26 
   27 %{C++
   28 #include "nsRect.h"
   29 class nsDocShellEditorData;
   30 class nsSHEntryShared;
   31 %}
   32 [ref] native nsIntRect(nsIntRect);
   33 [ptr] native nsDocShellEditorDataPtr(nsDocShellEditorData);
   34 [ptr] native nsSHEntryShared(nsSHEntryShared);
   35 
   36 [builtinclass, scriptable, uuid(0dad26b8-a259-42c7-93f1-2fa7fc076e45)]
   37 interface nsISHEntry : nsISupports
   38 {
   39     /**
   40      * The URI of the current entry.
   41      */
   42     [infallible] attribute nsIURI URI;
   43 
   44     /**
   45      * The original URI of the current entry. If an entry is the result of a
   46      * redirect this attribute holds the original URI.
   47      */
   48     [infallible] attribute nsIURI originalURI;
   49 
   50     /**
   51      * URL as stored from nsILoadInfo.resultPrincipalURI.  See nsILoadInfo
   52      * for more details.
   53      */
   54     [infallible] attribute nsIURI resultPrincipalURI;
   55 
   56     /**
   57      *  This flag remembers whether channel has LOAD_REPLACE set.
   58      */
   59     [infallible] attribute boolean loadReplace;
   60 
   61     /**
   62      * The title of the current entry.
   63      */
   64     // XXX: make it [infallible] when AString supports that (bug 1491187).
   65     attribute AString title;
   66 
   67     /**
   68      * Was the entry created as a result of a subframe navigation?
   69      * - Will be 'false' when a frameset page is visited for the first time.
   70      * - Will be 'true' for all history entries created as a result of a
   71      *   subframe navigation.
   72      */
   73     [infallible] attribute boolean isSubFrame;
   74 
   75     /** Referrer Info*/
   76     [infallible] attribute nsIReferrerInfo referrerInfo;
   77 
   78     /** Content viewer, for fast restoration of presentation */
   79     [infallible] attribute nsIContentViewer contentViewer;
   80 
   81     /** Whether the content viewer is marked "sticky" */
   82     [infallible] attribute boolean sticky;
   83 
   84     /** Saved state of the global window object */
   85     [infallible] attribute nsISupports windowState;
   86 
   87     /** Saved refresh URI list for the content viewer */
   88     [infallible] attribute nsIMutableArray refreshURIList;
   89 
   90     /** Post Data for the document */
   91     [infallible] attribute nsIInputStream postData;
   92 
   93     /** LayoutHistoryState for scroll position and form values */
   94     [infallible] attribute nsILayoutHistoryState layoutHistoryState;
   95 
   96     /** parent of this entry */
   97     [infallible] attribute nsISHEntry parent;
   98 
   99     /**
  100      * The loadType for this entry. This is typically loadHistory except
  101      * when reload is pressed, it has the appropriate reload flag
  102      */
  103     [infallible] attribute unsigned long loadType;
  104 
  105     /**
  106      * An ID to help identify this entry from others during
  107      * subframe navigation
  108      */
  109     [infallible] attribute unsigned long ID;
  110 
  111     /** The cache key for the entry */
  112     [infallible] attribute unsigned long cacheKey;
  113 
  114     /** Should the layoutHistoryState be saved? */
  115     [infallible] attribute boolean saveLayoutStateFlag;
  116 
  117     /** Has the page already expired in cache? */
  118     [infallible] attribute boolean expirationStatus;
  119 
  120     /**
  121      * attribute to indicate the content-type of the document that this
  122      * is a session history entry for
  123      */
  124     // XXX: make it [infallible] when ACString supports that (bug 1491187).
  125     attribute ACString contentType;
  126 
  127     /**
  128      * If we created this SHEntry via history.pushState or modified it via
  129      * history.replaceState, and if we changed the SHEntry's URI via the
  130      * push/replaceState call, and if the SHEntry's new URI differs from its
  131      * old URI by more than just the hash, then we set this field to true.
  132      *
  133      * Additionally, if this SHEntry was created by calling pushState from a
  134      * SHEntry whose URI was modified, this SHEntry's URIWasModified field is
  135      * true.
  136      */
  137     [infallible] attribute boolean URIWasModified;
  138 
  139     /**
  140      * Get the principal, if any, that was associated with the channel
  141      * that the document that was loaded to create this history entry
  142      * came from.
  143      */
  144     [infallible] attribute nsIPrincipal triggeringPrincipal;
  145 
  146     /**
  147      * Get the principal, if any, that is used when the inherit flag
  148      * is set.
  149      */
  150     [infallible] attribute nsIPrincipal principalToInherit;
  151 
  152     /**
  153      * Get the storage principal, if any, that is used when the inherit flag is
  154      * set.
  155      */
  156     [infallible] attribute nsIPrincipal storagePrincipalToInherit;
  157 
  158     /**
  159      * Get the csp, if any, that was used for this document load. That
  160      * is not the CSP that was applied to subresource loads within the
  161      * document, but the CSP that was applied to this document load.
  162      */
  163     [infallible] attribute nsIContentSecurityPolicy csp;
  164 
  165     /**
  166      * Get/set data associated with this history state via a pushState() call,
  167      * serialized using structured clone.
  168      **/
  169     [infallible] attribute nsIStructuredCloneContainer stateData;
  170 
  171     /**
  172      * The history ID of the docshell.
  173      */
  174     // Would be [infallible], but we don't support that property for nsIDPtr.
  175     attribute nsIDPtr docshellID;
  176 
  177     [infallible] readonly attribute nsIBFCacheEntry BFCacheEntry;
  178 
  179     /**
  180      * True if this SHEntry corresponds to a document created by a srcdoc
  181      * iframe. Set when a value is assigned to srcdocData.
  182      */
  183     [infallible] readonly attribute boolean isSrcdocEntry;
  184 
  185     /**
  186      * Contents of the srcdoc attribute in a srcdoc iframe to be loaded instead
  187      * of the URI.  Similar to a Data URI, this information is needed to
  188      * recreate the document at a later stage.
  189      * Setting this sets isSrcdocEntry to true
  190      */
  191     // XXX: make it [infallible] when AString supports that (bug 1491187).
  192     attribute AString srcdocData;
  193 
  194     /**
  195      * When isSrcdocEntry is true, this contains the baseURI of the srcdoc
  196      * document for use in situations where it cannot otherwise be determined,
  197      * for example with view-source.
  198      */
  199     [infallible] attribute nsIURI baseURI;
  200 
  201     /**
  202      * Sets/gets the current scroll restoration state,
  203      * if true == "manual", false == "auto".
  204      */
  205     [infallible] attribute boolean scrollRestorationIsManual;
  206 
  207     /**
  208      * Flag to indicate that the history entry was originally loaded in the
  209      * current process. This flag does not survive a browser process switch.
  210      */
  211     [infallible] readonly attribute boolean loadedInThisProcess;
  212 
  213     /**
  214      * The session history it belongs to. It's usually only set on root entries.
  215      * SHEntry is strictly bound to the SHistory it belongs to; it should not be
  216      * changed once set to a non-null value.
  217      */
  218     [noscript, infallible] attribute nsISHistory SHistory;
  219 
  220     /**
  221      * A number that is assigned by the sHistory when the entry is activated
  222      */
  223     [noscript, infallible] attribute unsigned long lastTouched;
  224 
  225     /**
  226      * The current number of nsISHEntries which are immediate children of this
  227      * SHEntry.
  228      */
  229     [infallible] readonly attribute long childCount;
  230 
  231     /**
  232      * When an entry is serving is within nsISHistory's array of entries, this
  233      * property specifies if it should persist. If not it will be replaced by
  234      * new additions to the list.
  235      */
  236     [infallible] attribute boolean persist;
  237 
  238     /**
  239      * Set/Get the visual viewport scroll position if session history is
  240      * changed through anchor navigation or pushState.
  241      */
  242     void setScrollPosition(in long x, in long y);
  243     void getScrollPosition(out long x, out long y);
  244 
  245     /**
  246      * Saved position and dimensions of the content viewer; we must adjust the
  247      * root view's widget accordingly if this has changed when the presentation
  248      * is restored.
  249      */
  250     [noscript, notxpcom] void getViewerBounds(in nsIntRect bounds);
  251     [noscript, notxpcom] void setViewerBounds([const] in nsIntRect bounds);
  252 
  253     /**
  254      * Saved child docshells corresponding to contentViewer.  The child shells
  255      * are restored as children of the parent docshell, in this order, when the
  256      * parent docshell restores a saved presentation.
  257      */
  258 
  259     /** Append a child shell to the end of our list. */
  260     [noscript, notxpcom] void addChildShell(in nsIDocShellTreeItem shell);
  261 
  262     /**
  263      * Get the child shell at |index|; returns null if |index| is out of bounds.
  264      */
  265     [noscript] nsIDocShellTreeItem childShellAt(in long index);
  266 
  267     /**
  268      * Clear the child shell list.
  269      */
  270     [noscript, notxpcom] void clearChildShells();
  271 
  272     /**
  273      * Ensure that the cached presentation members are self-consistent.
  274      * If either |contentViewer| or |windowState| are null, then all of the
  275      * following members are cleared/reset:
  276      *  contentViewer, sticky, windowState, viewerBounds, childShells,
  277      *  refreshURIList.
  278      */
  279     [noscript, notxpcom] void syncPresentationState();
  280 
  281     /**
  282      * Initialises `layoutHistoryState` if it doesn't already exist
  283      * and returns a reference to it.
  284      */
  285     nsILayoutHistoryState initLayoutHistoryState();
  286 
  287     /** Additional ways to create an entry */
  288     [noscript] void create(in nsIURI URI, in AString title,
  289                            in nsIInputStream inputStream,
  290                            in nsILayoutHistoryState layoutHistoryState,
  291                            in unsigned long cacheKey, in ACString contentType,
  292                            in nsIPrincipal triggeringPrincipal,
  293                            in nsIPrincipal principalToInherit,
  294                            in nsIPrincipal storagePrincipalToInherit,
  295                            in nsIContentSecurityPolicy aCsp,
  296                            in nsIDRef docshellID,
  297                            in boolean dynamicCreation);
  298 
  299     nsISHEntry clone();
  300 
  301     /**
  302      * Gets the owning pointer to the editor data assosicated with
  303      * this shistory entry. This forgets its pointer, so free it when
  304      * you're done.
  305      */
  306     [noscript, notxpcom] nsDocShellEditorDataPtr forgetEditorData();
  307 
  308     /**
  309      * Sets the owning pointer to the editor data assosicated with
  310      * this shistory entry. Unless forgetEditorData() is called, this
  311      * shentry will destroy the editor data when it's destroyed.
  312      */
  313     [noscript, notxpcom] void setEditorData(in nsDocShellEditorDataPtr aData);
  314 
  315     /** Returns true if this shistory entry is storing a detached editor. */
  316     [noscript, notxpcom] boolean hasDetachedEditor();
  317 
  318     /**
  319      * Returns true if the related docshell was added because of
  320      * dynamic addition of an iframe/frame.
  321      */
  322     [noscript, notxpcom] boolean isDynamicallyAdded();
  323 
  324     /**
  325      * Returns true if any of the child entries returns true
  326      * when isDynamicallyAdded is called on it.
  327      */
  328     boolean hasDynamicallyAddedChild();
  329 
  330     /**
  331      * Helper method for accessing `docshellID` from C++
  332      */
  333     [noscript, notxpcom] nsID DocshellID();
  334 
  335     /**
  336      * Does this SHEntry point to the given BFCache entry? If so, evicting
  337      * the BFCache entry will evict the SHEntry, since the two entries
  338      * correspond to the same document.
  339      */
  340     [noscript, notxpcom] boolean hasBFCacheEntry(in nsIBFCacheEntry aEntry);
  341 
  342     /**
  343      * Adopt aEntry's BFCacheEntry, so now both this and aEntry point to
  344      * aEntry's BFCacheEntry.
  345      */
  346     void adoptBFCacheEntry(in nsISHEntry aEntry);
  347 
  348     /**
  349      * Create a new BFCache entry and drop our reference to our old one. This
  350      * call unlinks this SHEntry from any other SHEntries for its document.
  351      */
  352     void abandonBFCacheEntry();
  353 
  354     /**
  355      * Does this SHEntry correspond to the same document as aEntry? This is
  356      * true iff the two SHEntries have the same BFCacheEntry. So in particular,
  357      * sharesDocumentWith(aEntry) is guaranteed to return true if it's
  358      * preceded by a call to adoptBFCacheEntry(aEntry).
  359      */
  360     boolean sharesDocumentWith(in nsISHEntry aEntry);
  361 
  362     /**
  363      * Sets an SHEntry to reflect that it is a history type load. As
  364      * nsIDocShellLoadInfo and its LoadType enum were removed, this is the
  365      * equivalent to doing
  366      *
  367      * shEntry.loadType = 4;
  368      *
  369      * in js, but easier to maintain and less opaque.
  370      */
  371     void setLoadTypeAsHistory();
  372 
  373     /**
  374      * Some state, particularly that related to the back/forward cache, is
  375      * shared between SHEntries which correspond to the same document.  This
  376      * method gets a pointer to that shared state.
  377      *
  378      * This shared state is the SHEntry's BFCacheEntry.  So
  379      * hasBFCacheEntry(getSharedState()) is guaranteed to return true.
  380      */
  381     [noscript, notxpcom] nsSHEntryShared getSharedState();
  382 
  383     /**
  384      * Add a new child SHEntry. If offset is -1 adds to the end of the list.
  385      */
  386     void AddChild(in nsISHEntry aChild, in long aOffset);
  387 
  388     /**
  389      * Remove a child SHEntry.
  390      */
  391     [noscript] void RemoveChild(in nsISHEntry aChild);
  392 
  393     /**
  394      * Get child at an index.
  395      */
  396     nsISHEntry GetChildAt(in long aIndex);
  397 
  398     /**
  399      * Replaces a child which is for the same docshell as aNewChild
  400      * with aNewChild.
  401      * @throw if nothing was replaced.
  402      */
  403     [noscript] void ReplaceChild(in nsISHEntry aNewChild);
  404 };
  405