1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docshell/shistory/public/nsISHEntry.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,321 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +/**
1.10 + * The interface to nsISHentry. Each document or subframe in
1.11 + * Session History will have a nsISHEntry associated with it which will
1.12 + * hold all information required to recreate the document from history
1.13 + *
1.14 + */
1.15 +
1.16 +#include "nsISupports.idl"
1.17 +
1.18 +interface nsILayoutHistoryState;
1.19 +interface nsIContentViewer;
1.20 +interface nsIURI;
1.21 +interface nsIInputStream;
1.22 +interface nsIDocShellTreeItem;
1.23 +interface nsISupportsArray;
1.24 +interface nsIStructuredCloneContainer;
1.25 +interface nsIBFCacheEntry;
1.26 +
1.27 +%{C++
1.28 +struct nsIntRect;
1.29 +class nsDocShellEditorData;
1.30 +class nsSHEntryShared;
1.31 +%}
1.32 +[ref] native nsIntRect(nsIntRect);
1.33 +[ptr] native nsDocShellEditorDataPtr(nsDocShellEditorData);
1.34 +[ptr] native nsSHEntryShared(nsSHEntryShared);
1.35 +
1.36 +[scriptable, uuid(9eed7e92-1121-46f2-95e5-2f5c0dca46f0)]
1.37 +interface nsISHEntry : nsISupports
1.38 +{
1.39 + /**
1.40 + * A readonly property that returns the URI
1.41 + * of the current entry. The object returned is
1.42 + * of type nsIURI
1.43 + */
1.44 + readonly attribute nsIURI URI;
1.45 +
1.46 + /**
1.47 + * A readonly property that returns the title
1.48 + * of the current entry. The object returned
1.49 + * is a encoded string
1.50 + */
1.51 + readonly attribute wstring title;
1.52 +
1.53 + /**
1.54 + * A readonly property that returns a boolean
1.55 + * flag which indicates if the entry was created as a
1.56 + * result of a subframe navigation. This flag will be
1.57 + * 'false' when a frameset page is visited for
1.58 + * the first time. This flag will be 'true' for all
1.59 + * history entries created as a result of a subframe
1.60 + * navigation.
1.61 + */
1.62 + readonly attribute boolean isSubFrame;
1.63 +
1.64 + /** URI for the document */
1.65 + void setURI(in nsIURI aURI);
1.66 +
1.67 + /** Referrer URI */
1.68 + attribute nsIURI referrerURI;
1.69 +
1.70 + /** Content viewer, for fast restoration of presentation */
1.71 + attribute nsIContentViewer contentViewer;
1.72 +
1.73 + /** Whether the content viewer is marked "sticky" */
1.74 + attribute boolean sticky;
1.75 +
1.76 + /** Saved state of the global window object */
1.77 + attribute nsISupports windowState;
1.78 +
1.79 + /**
1.80 + * Saved position and dimensions of the content viewer; we must adjust the
1.81 + * root view's widget accordingly if this has changed when the presentation
1.82 + * is restored.
1.83 + */
1.84 + [noscript] void getViewerBounds(in nsIntRect bounds);
1.85 + [noscript] void setViewerBounds([const] in nsIntRect bounds);
1.86 +
1.87 + /**
1.88 + * Saved child docshells corresponding to contentViewer. The child shells
1.89 + * are restored as children of the parent docshell, in this order, when the
1.90 + * parent docshell restores a saved presentation.
1.91 + */
1.92 +
1.93 + /** Append a child shell to the end of our list. */
1.94 + void addChildShell(in nsIDocShellTreeItem shell);
1.95 +
1.96 + /**
1.97 + * Get the child shell at |index|; returns null if |index| is out of bounds.
1.98 + */
1.99 + nsIDocShellTreeItem childShellAt(in long index);
1.100 +
1.101 + /**
1.102 + * Clear the child shell list.
1.103 + */
1.104 + void clearChildShells();
1.105 +
1.106 + /** Saved refresh URI list for the content viewer */
1.107 + attribute nsISupportsArray refreshURIList;
1.108 +
1.109 + /**
1.110 + * Ensure that the cached presentation members are self-consistent.
1.111 + * If either |contentViewer| or |windowState| are null, then all of the
1.112 + * following members are cleared/reset:
1.113 + * contentViewer, sticky, windowState, viewerBounds, childShells,
1.114 + * refreshURIList.
1.115 + */
1.116 + void syncPresentationState();
1.117 +
1.118 + /** Title for the document */
1.119 + void setTitle(in AString aTitle);
1.120 +
1.121 + /** Post Data for the document */
1.122 + attribute nsIInputStream postData;
1.123 +
1.124 + /** LayoutHistoryState for scroll position and form values */
1.125 + attribute nsILayoutHistoryState layoutHistoryState;
1.126 +
1.127 + /** parent of this entry */
1.128 + attribute nsISHEntry parent;
1.129 +
1.130 + /**
1.131 + * The loadType for this entry. This is typically loadHistory except
1.132 + * when reload is pressed, it has the appropriate reload flag
1.133 + */
1.134 + attribute unsigned long loadType;
1.135 +
1.136 + /**
1.137 + * An ID to help identify this entry from others during
1.138 + * subframe navigation
1.139 + */
1.140 + attribute unsigned long ID;
1.141 +
1.142 + /** attribute to set and get the cache key for the entry */
1.143 + attribute nsISupports cacheKey;
1.144 +
1.145 + /** attribute to indicate whether layoutHistoryState should be saved */
1.146 + attribute boolean saveLayoutStateFlag;
1.147 +
1.148 + /** attribute to indicate whether the page is already expired in cache */
1.149 + attribute boolean expirationStatus;
1.150 +
1.151 + /**
1.152 + * attribute to indicate the content-type of the document that this
1.153 + * is a session history entry for
1.154 + */
1.155 + attribute ACString contentType;
1.156 +
1.157 + /**
1.158 + * If we created this SHEntry via history.pushState or modified it via
1.159 + * history.replaceState, and if we changed the SHEntry's URI via the
1.160 + * push/replaceState call, and if the SHEntry's new URI differs from its
1.161 + * old URI by more than just the hash, then we set this field to true.
1.162 + *
1.163 + * Additionally, if this SHEntry was created by calling pushState from a
1.164 + * SHEntry whose URI was modified, this SHEntry's URIWasModified field is
1.165 + * true.
1.166 + *
1.167 + */
1.168 + attribute boolean URIWasModified;
1.169 +
1.170 + /** Set/Get scrollers' positon in anchored pages */
1.171 + void setScrollPosition(in long x, in long y);
1.172 + void getScrollPosition(out long x, out long y);
1.173 +
1.174 + /** Additional ways to create an entry */
1.175 + [noscript] void create(in nsIURI URI, in AString title,
1.176 + in nsIInputStream inputStream,
1.177 + in nsILayoutHistoryState layoutHistoryState,
1.178 + in nsISupports cacheKey, in ACString contentType,
1.179 + in nsISupports owner,
1.180 + in unsigned long long docshellID,
1.181 + in boolean dynamicCreation);
1.182 +
1.183 + nsISHEntry clone();
1.184 +
1.185 + /** Attribute that indicates if this entry is for a subframe navigation */
1.186 + void setIsSubFrame(in boolean aFlag);
1.187 +
1.188 + /** Return any content viewer present in or below this node in the
1.189 + nsSHEntry tree. This will differ from contentViewer in the case
1.190 + where a child nsSHEntry has the content viewer for this tree. */
1.191 + nsIContentViewer getAnyContentViewer(out nsISHEntry ownerEntry);
1.192 +
1.193 + /**
1.194 + * Get the owner, if any, that was associated with the channel
1.195 + * that the document that was loaded to create this history entry
1.196 + * came from.
1.197 + */
1.198 + attribute nsISupports owner;
1.199 +
1.200 + /**
1.201 + * Get/set data associated with this history state via a pushState() call,
1.202 + * serialized using structured clone.
1.203 + **/
1.204 + attribute nsIStructuredCloneContainer stateData;
1.205 +
1.206 + /**
1.207 + * Gets the owning pointer to the editor data assosicated with
1.208 + * this shistory entry. This forgets its pointer, so free it when
1.209 + * you're done.
1.210 + */
1.211 + [noscript, notxpcom] nsDocShellEditorDataPtr forgetEditorData();
1.212 +
1.213 + /**
1.214 + * Sets the owning pointer to the editor data assosicated with
1.215 + * this shistory entry. Unless forgetEditorData() is called, this
1.216 + * shentry will destroy the editor data when it's destroyed.
1.217 + */
1.218 + [noscript, notxpcom] void setEditorData(in nsDocShellEditorDataPtr aData);
1.219 +
1.220 + /** Returns true if this shistory entry is storing a detached editor. */
1.221 + [noscript, notxpcom] boolean hasDetachedEditor();
1.222 +
1.223 + /**
1.224 + * Returns true if the related docshell was added because of
1.225 + * dynamic addition of an iframe/frame.
1.226 + */
1.227 + boolean isDynamicallyAdded();
1.228 +
1.229 + /**
1.230 + * Returns true if any of the child entries returns true
1.231 + * when isDynamicallyAdded is called on it.
1.232 + */
1.233 + boolean hasDynamicallyAddedChild();
1.234 +
1.235 + /**
1.236 + * The history ID of the docshell.
1.237 + */
1.238 + attribute unsigned long long docshellID;
1.239 +
1.240 + readonly attribute nsIBFCacheEntry BFCacheEntry;
1.241 +
1.242 + /**
1.243 + * Does this SHEntry point to the given BFCache entry? If so, evicting
1.244 + * the BFCache entry will evict the SHEntry, since the two entries
1.245 + * correspond to the same document.
1.246 + */
1.247 + [notxpcom, noscript]
1.248 + boolean hasBFCacheEntry(in nsIBFCacheEntry aEntry);
1.249 +
1.250 + /**
1.251 + * Adopt aEntry's BFCacheEntry, so now both this and aEntry point to
1.252 + * aEntry's BFCacheEntry.
1.253 + */
1.254 + void adoptBFCacheEntry(in nsISHEntry aEntry);
1.255 +
1.256 + /**
1.257 + * Create a new BFCache entry and drop our reference to our old one. This
1.258 + * call unlinks this SHEntry from any other SHEntries for its document.
1.259 + */
1.260 + void abandonBFCacheEntry();
1.261 +
1.262 + /**
1.263 + * Does this SHEntry correspond to the same document as aEntry? This is
1.264 + * true iff the two SHEntries have the same BFCacheEntry. So in
1.265 + * particular, sharesDocumentWith(aEntry) is guaranteed to return true if
1.266 + * it's preceeded by a call to adoptBFCacheEntry(aEntry).
1.267 + */
1.268 + boolean sharesDocumentWith(in nsISHEntry aEntry);
1.269 +
1.270 + /**
1.271 + * True if this SHEntry corresponds to a document created by a srcdoc iframe.
1.272 + * Set when a value is assigned to srcdocData.
1.273 + */
1.274 + readonly attribute boolean isSrcdocEntry;
1.275 +
1.276 + /**
1.277 + * Contents of the srcdoc attribute in a srcdoc iframe to be loaded instead
1.278 + * of the URI. Similar to a Data URI, this information is needed to
1.279 + * recreate the document at a later stage.
1.280 + * Setting this sets isSrcdocEntry to true
1.281 + */
1.282 + attribute AString srcdocData;
1.283 +
1.284 + /**
1.285 + * When isSrcdocEntry is true, this contains the baseURI of the srcdoc
1.286 + * document for use in situations where it cannot otherwise be determined,
1.287 + * for example with view-source.
1.288 + */
1.289 + attribute nsIURI baseURI;
1.290 +};
1.291 +
1.292 +[scriptable, uuid(bb66ac35-253b-471f-a317-3ece940f04c5)]
1.293 +interface nsISHEntryInternal : nsISupports
1.294 +{
1.295 + [notxpcom] void RemoveFromBFCacheAsync();
1.296 + [notxpcom] void RemoveFromBFCacheSync();
1.297 +
1.298 + /**
1.299 + * A number that is assigned by the sHistory when the entry is activated
1.300 + */
1.301 + attribute unsigned long lastTouched;
1.302 +
1.303 + /**
1.304 + * Some state, particularly that related to the back/forward cache, is
1.305 + * shared between SHEntries which correspond to the same document. This
1.306 + * method gets a pointer to that shared state.
1.307 + *
1.308 + * This shared state is the SHEntry's BFCacheEntry. So
1.309 + * hasBFCacheEntry(getSharedState()) is guaranteed to return true.
1.310 + */
1.311 + [noscript, notxpcom]
1.312 + nsSHEntryShared getSharedState();
1.313 +};
1.314 +
1.315 +%{ C++
1.316 +// {BFD1A791-AD9F-11d3-BDC7-0050040A9B44}
1.317 +#define NS_SHENTRY_CID \
1.318 +{0xbfd1a791, 0xad9f, 0x11d3, {0xbd, 0xc7, 0x0, 0x50, 0x4, 0xa, 0x9b, 0x44}}
1.319 +
1.320 +#define NS_SHENTRY_CONTRACTID \
1.321 + "@mozilla.org/browser/session-history-entry;1"
1.322 +
1.323 +%}
1.324 +
