docshell/shistory/public/nsISHEntry.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *   Radha Kulkarni <radha@netscape.com>
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either of the GNU General Public License Version 2 or later (the "GPL"),
  27  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28  * in which case the provisions of the GPL or the LGPL are applicable instead
  29  * of those above. If you wish to allow use of your version of this file only
  30  * under the terms of either the GPL or the LGPL, and not to allow others to
  31  * use your version of this file under the terms of the MPL, indicate your
  32  * decision by deleting the provisions above and replace them with the notice
  33  * and other provisions required by the GPL or the LGPL. If you do not delete
  34  * the provisions above, a recipient may use your version of this file under
  35  * the terms of any one of the MPL, the GPL or the LGPL.
  36  *
  37  * ***** END LICENSE BLOCK ***** */
  38
  39 /**
  40  * The interface to nsISHentry. Each document or subframe in
  41  * Session History will have a nsISHEntry associated with it which will
  42  * hold all information required to recreate the document from history
  43  *
  44  */
  45 #include "nsIHistoryEntry.idl"
  46
  47 interface nsILayoutHistoryState;
  48 interface nsIContentViewer;
  49 interface nsIURI;
  50 interface nsIInputStream;
  51 interface nsIDocShellTreeItem;
  52 interface nsISupportsArray;
  53 %{C++
  54 struct nsIntRect;
  55 class nsDocShellEditorData;
  56 %}
  57 [ref] native nsIntRect(nsIntRect);
  58 [ptr] native nsDocShellEditorDataPtr(nsDocShellEditorData);
  59
  60
  61 [scriptable, uuid(39b73c3a-48eb-4189-8069-247279c3c42d)]
  62 interface nsISHEntry : nsIHistoryEntry
  63 {
  64     /** URI for the document */
  65     void setURI(in nsIURI aURI);
  66
  67     /** Referrer URI */
  68     attribute nsIURI referrerURI;
  69
  70     /** Content viewer, for fast restoration of presentation */
  71     attribute nsIContentViewer contentViewer;
  72
  73     /** Whether the content viewer is marked "sticky" */
  74     attribute boolean sticky;
  75
  76     /** Saved state of the global window object */
  77     attribute nsISupports windowState;
  78
  79     /**
  80      * Saved position and dimensions of the content viewer; we must adjust the
  81      * root view's widget accordingly if this has changed when the presentation
  82      * is restored.
  83      */
  84     [noscript] void getViewerBounds(in nsIntRect bounds);
  85     [noscript] void setViewerBounds([const] in nsIntRect bounds);
  86
  87     /**
  88      * Saved child docshells corresponding to contentViewer.  The child shells
  89      * are restored as children of the parent docshell, in this order, when the
  90      * parent docshell restores a saved presentation.
  91      */
  92
  93     /** Append a child shell to the end of our list. */
  94     void addChildShell(in nsIDocShellTreeItem shell);
  95
  96     /**
  97      * Get the child shell at |index|; returns null if |index| is out of bounds.
  98      */
  99     nsIDocShellTreeItem childShellAt(in long index);
 100
 101     /**
 102      * Clear the child shell list.
 103      */
 104     void clearChildShells();
 105
 106     /** Saved refresh URI list for the content viewer */
 107     attribute nsISupportsArray refreshURIList;
 108
 109     /**
 110      * Ensure that the cached presentation members are self-consistent.
 111      * If either |contentViewer| or |windowState| are null, then all of the
 112      * following members are cleared/reset:
 113      *  contentViewer, sticky, windowState, viewerBounds, childShells,
 114      *  refreshURIList.
 115      */
 116     void syncPresentationState();
 117
 118     /** Title for the document */
 119     void setTitle(in AString aTitle);
 120
 121     /** Post Data for the document */
 122     attribute nsIInputStream postData;
 123
 124     /** LayoutHistoryState for scroll position and form values */
 125     attribute nsILayoutHistoryState layoutHistoryState;
 126
 127     /** parent of this entry */
 128     attribute nsISHEntry parent;
 129
 130     /**
 131      * The loadType for this entry. This is typically loadHistory except
 132      * when reload is pressed, it has the appropriate reload flag
 133      */
 134     attribute unsigned long loadType;
 135
 136     /**
 137      * An ID to help identify this entry from others during
 138      * subframe navigation
 139      */
 140     attribute unsigned long ID;
 141
 142     /**
 143      * pageIdentifier is an integer that should be the same for two entries
 144      * attached to the same docshell only if the two entries are entries for
 145      * the same page in the sense that one could go from the state represented
 146      * by one to the state represented by the other simply by scrolling (so the
 147      * entries are separated by an anchor traversal or a subframe navigation in
 148      * some other frame).
 149      */
 150     attribute unsigned long pageIdentifier;
 151
 152     /**
 153      * docIdentifier is an integer that should be the same for two entries
 154      * attached to the same docshell if and only if the two entries are entries
 155      * for the same document.  In practice, two entries A and B will have the
 156      * same docIdentifier if they have the same pageIdentifier or if B was
 157      * created by A calling history.pushState().
 158      */
 159     attribute unsigned long long docIdentifier;
 160
 161     /**
 162      * Changes this entry's doc identifier to a new value which is unique
 163      * among those of all other entries.
 164      */
 165     void setUniqueDocIdentifier();
 166
 167     /** attribute to set and get the cache key for the entry */
 168     attribute nsISupports cacheKey;
 169
 170     /** attribute to indicate whether layoutHistoryState should be saved */
 171     attribute boolean saveLayoutStateFlag;
 172
 173     /** attribute to indicate whether the page is already expired in cache */
 174     attribute boolean expirationStatus;
 175
 176     /**
 177      * attribute to indicate the content-type of the document that this
 178      * is a session history entry for
 179      */
 180     attribute ACString contentType;
 181
 182     /** Set/Get scrollers' positon in anchored pages */
 183     void setScrollPosition(in long x, in long y);
 184     void getScrollPosition(out long x, out long y);
 185
 186     /** Additional ways to create an entry */
 187     [noscript] void create(in nsIURI URI, in AString title,
 188                            in nsIInputStream inputStream,
 189                            in nsILayoutHistoryState layoutHistoryState,
 190                            in nsISupports cacheKey, in ACString contentType,
 191                            in nsISupports owner,
 192                            in unsigned long long docshellID,
 193                            in boolean dynamicCreation);
 194
 195     nsISHEntry clone();
 196
 197     /** Attribute that indicates if this entry is for a subframe navigation */
 198     void setIsSubFrame(in boolean aFlag);
 199
 200     /** Return any content viewer present in or below this node in the
 201         nsSHEntry tree.  This will differ from contentViewer in the case
 202         where a child nsSHEntry has the content viewer for this tree. */
 203     nsIContentViewer getAnyContentViewer(out nsISHEntry ownerEntry);
 204
 205     /**
 206      * Get the owner, if any, that was associated with the channel
 207      * that the document that was loaded to create this history entry
 208      * came from.
 209      */
 210     attribute nsISupports owner;
 211
 212     /**
 213      * Get/set data associated with this history state via a pushState() call,
 214      * encoded as JSON.
 215      **/
 216     attribute AString stateData;
 217
 218     /**
 219      * Gets the owning pointer to the editor data assosicated with
 220      * this shistory entry. This forgets its pointer, so free it when
 221      * you're done.
 222      */
 223     [noscript, notxpcom] nsDocShellEditorDataPtr forgetEditorData();
 224
 225     /**
 226      * Sets the owning pointer to the editor data assosicated with
 227      * this shistory entry. Unless forgetEditorData() is called, this
 228      * shentry will destroy the editor data when it's destroyed.
 229      */
 230     [noscript, notxpcom] void setEditorData(in nsDocShellEditorDataPtr aData);
 231
 232     /** Returns true if this shistory entry is storing a detached editor. */
 233     [noscript, notxpcom] boolean hasDetachedEditor();
 234
 235     /**
 236      * Returns true if the related docshell was added because of
 237      * dynamic addition of an iframe/frame.
 238      */
 239     boolean isDynamicallyAdded();
 240
 241     /**
 242      * Returns true if any of the child entries returns true
 243      * when isDynamicallyAdded is called on it.
 244      */
 245     boolean hasDynamicallyAddedChild();
 246
 247     /**
 248      * The history ID of the docshell.
 249      */
 250     attribute unsigned long long docshellID;
 251 };
 252
 253 [scriptable, uuid(bb66ac35-253b-471f-a317-3ece940f04c5)]
 254 interface nsISHEntryInternal : nsISupports
 255 {
 256     [notxpcom] void RemoveFromBFCacheAsync();
 257     [notxpcom] void RemoveFromBFCacheSync();
 258
 259     /**
 260      * A number that is assigned by the sHistory when the entry is activated
 261      */
 262     attribute unsigned long lastTouched;
 263 };
 264
 265 %{ C++
 266 // {BFD1A791-AD9F-11d3-BDC7-0050040A9B44}
 267 #define NS_SHENTRY_CID \
 268 {0xbfd1a791, 0xad9f, 0x11d3, {0xbd, 0xc7, 0x0, 0x50, 0x4, 0xa, 0x9b, 0x44}}
 269
 270 #define NS_SHENTRY_CONTRACTID \
 271     "@mozilla.org/browser/session-history-entry;1"
 272
 273 %}
 274