1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
3 * ***** BEGIN LICENSE BLOCK *****
4 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
6 * The contents of this file are subject to the Mozilla Public License Version
7 * 1.1 (the "License"); you may not use this file except in compliance with
8 * the License. You may obtain a copy of the License at
9 * http://www.mozilla.org/MPL/
11 * Software distributed under the License is distributed on an "AS IS" basis,
12 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
13 * for the specific language governing rights and limitations under the
16 * The Original Code is the Mozilla browser.
18 * The Initial Developer of the Original Code is
19 * Netscape Communications, Inc.
20 * Portions created by the Initial Developer are Copyright (C) 1999
21 * the Initial Developer. All Rights Reserved.
24 * Travis Bogard <travis@netscape.com>
25 * Steve Clark <buster@netscape.com>
27 * Alternatively, the contents of this file may be used under the terms of
28 * either of the GNU General Public License Version 2 or later (the "GPL"),
29 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
30 * in which case the provisions of the GPL or the LGPL are applicable instead
31 * of those above. If you wish to allow use of your version of this file only
32 * under the terms of either the GPL or the LGPL, and not to allow others to
33 * use your version of this file under the terms of the MPL, indicate your
34 * decision by deleting the provisions above and replace them with the notice
35 * and other provisions required by the GPL or the LGPL. If you do not delete
36 * the provisions above, a recipient may use your version of this file under
37 * the terms of any one of the MPL, the GPL or the LGPL.
39 * ***** END LICENSE BLOCK ***** */
41 #include
"nsISupports.idl"
49 * The nsIDocShell interface.
52 [ptr] native nsPresContext
(nsPresContext
);
53 [ptr] native nsIPresShell
(nsIPresShell
);
57 interface nsIContentViewer
;
58 interface nsIURIContentListener
;
59 interface nsIDOMEventTarget
;
60 interface nsIDocShellLoadInfo
;
61 interface nsIDocumentCharsetInfo
;
62 interface nsIWebNavigation
;
63 interface nsISimpleEnumerator
;
64 interface nsIInputStream
;
67 interface nsILayoutHistoryState
;
68 interface nsISecureBrowserUI
;
69 interface nsIDOMStorage
;
70 interface nsIPrincipal
;
71 interface nsIWebBrowserPrint
;
74 [scriptable
, uuid(98cdbcc4
-2d81
-4191-a63f
-b6c52085edbc
)]
75 interface nsIDocShell
: nsISupports
78 * Loads a given URI. This will give priority to loading the requested URI
79 * in the object implementing this interface. If it can't be loaded here
80 * however, the URL dispatcher will go through its normal process of content
83 * @param uri - The URI to load.
84 * @param loadInfo - This is the extended load info for this load. This
85 * most often will be null, but if you need to do
86 * additional setup for this load you can get a loadInfo
87 * object by calling createLoadInfo. Once you have this
88 * object you can set the needed properties on it and
89 * then pass it to loadURI.
90 * @param aLoadFlags - Flags to modify load behaviour. Flags are defined in
91 * nsIWebNavigation. Note that using flags outside
92 * LOAD_FLAGS_MASK is only allowed if passing in a
93 * non-null loadInfo. And even some of those might not
94 * be allowed. Use at your own risk.
96 [noscript
]void loadURI
(in nsIURI uri
,
97 in nsIDocShellLoadInfo loadInfo
,
98 in unsigned long aLoadFlags
,
99 in boolean firstParty
);
102 * Loads a given stream. This will give priority to loading the requested
103 * stream in the object implementing this interface. If it can't be loaded
104 * here however, the URL dispatched will go through its normal process of
107 * @param aStream - The input stream that provides access to the data
108 * to be loaded. This must be a blocking, threadsafe
109 * stream implementation.
110 * @param aURI - The URI representing the stream, or null.
111 * @param aContentType - The type (MIME) of data being loaded (empty if unknown).
112 * @param aContentCharset - The charset of the data being loaded (empty if unknown).
113 * @param aLoadInfo - This is the extended load info for this load. This
114 * most often will be null, but if you need to do
115 * additional setup for this load you can get a
116 * loadInfo object by calling createLoadInfo. Once
117 * you have this object you can set the needed
118 * properties on it and then pass it to loadStream.
120 [noscript
]void loadStream
(in nsIInputStream aStream
,
122 in ACString aContentType
,
123 in ACString aContentCharset
,
124 in nsIDocShellLoadInfo aLoadInfo
);
126 const long INTERNAL_LOAD_FLAGS_NONE
= 0x0;
127 const long INTERNAL_LOAD_FLAGS_INHERIT_OWNER
= 0x1;
128 const long INTERNAL_LOAD_FLAGS_DONT_SEND_REFERRER
= 0x2;
129 const long INTERNAL_LOAD_FLAGS_ALLOW_THIRD_PARTY_FIXUP
= 0x4;
131 // This flag marks the first load in this object
132 // @see nsIWebNavigation::LOAD_FLAGS_FIRST_LOAD
133 const long INTERNAL_LOAD_FLAGS_FIRST_LOAD
= 0x8;
135 const long INTERNAL_LOAD_FLAGS_BYPASS_CLASSIFIER
= 0x10;
136 const long INTERNAL_LOAD_FLAGS_FORCE_ALLOW_COOKIES
= 0x20;
139 * Loads the given URI. This method is identical to loadURI(...) except
140 * that its parameter list is broken out instead of being packaged inside
141 * of an nsIDocShellLoadInfo object...
143 * @param aURI - The URI to load.
144 * @param aReferrer - Referring URI
145 * @param aOwner - Owner (security principal)
146 * @param aInheritOwner - Flag indicating whether the owner of the current
147 * document should be inherited if aOwner is null.
148 * @param aStopActiveDoc - Flag indicating whether loading the current
149 * document should be stopped.
150 * @param aWindowTarget - Window target for the load.
151 * @param aTypeHint - A hint as to the content-type of the resulting
152 * data. May be null or empty if no hint.
153 * @param aPostDataStream - Post data stream (if POSTing)
154 * @param aHeadersStream - Stream containing "extra" request headers...
155 * @param aLoadFlags - Flags to modify load behaviour. Flags are defined
156 * in nsIWebNavigation.
157 * @param aSHEntry - Active Session History entry (if loading from SH)
159 [noscript
]void internalLoad
(in nsIURI aURI
,
161 in nsISupports aOwner
,
163 in wstring aWindowTarget
,
165 in nsIInputStream aPostDataStream
,
166 in nsIInputStream aHeadersStream
,
167 in unsigned long aLoadFlags
,
168 in nsISHEntry aSHEntry
,
169 in boolean firstParty
,
170 out nsIDocShell aDocShell
,
171 out nsIRequest aRequest
);
174 * Do either a history.pushState() or history.replaceState() operation,
175 * depending on the value of aReplace.
177 void addState
(in nsIVariant aData
, in DOMString aTitle
,
178 in DOMString aURL
, in boolean aReplace
);
181 * Creates a DocShellLoadInfo object that you can manipulate and then pass
184 void createLoadInfo
(out nsIDocShellLoadInfo loadInfo
);
187 * Reset state to a new content model within the current document and the document
188 * viewer. Called by the document before initiating an out of band document.write().
190 void prepareForNewContentModel
();
193 * For editors and suchlike who wish to change the URI associated with the
194 * document. Note if you want to get the current URI, use the read-only
195 * property on nsIWebNavigation.
197 void setCurrentURI
(in nsIURI aURI
);
200 * Notify the associated content viewer and all child docshells that they are
201 * about to be hidden. If |isUnload| is true, then the document is being
204 * @param isUnload if true, fire the unload event in addition to the pagehide
207 [noscript
] void firePageHideNotification
(in boolean isUnload
);
210 * Presentation context for the currently loaded document. This may be null.
212 [noscript
] readonly attribute nsPresContext presContext
;
215 * Presentation shell for the currently loaded document. This may be null.
217 [noscript
] readonly attribute nsIPresShell presShell
;
220 * Presentation shell for the oldest document, if this docshell is
221 * currently transitioning between documents.
223 [noscript
] readonly attribute nsIPresShell eldestPresShell
;
226 * Content Viewer that is currently loaded for this DocShell. This may
227 * change as the underlying content changes.
229 readonly attribute nsIContentViewer contentViewer
;
232 * This attribute allows chrome to tie in to handle DOM events that may
233 * be of interest to chrome.
235 attribute nsIDOMEventTarget chromeEventHandler
;
238 * The document charset info. This is used by a load to determine priorities
239 * for charset detection etc.
241 attribute nsIDocumentCharsetInfo documentCharsetInfo
;
244 * Whether to allow plugin execution
246 attribute
boolean allowPlugins
;
249 * Whether to allow Javascript execution
251 attribute
boolean allowJavascript
;
254 * Attribute stating if refresh based redirects can be allowed
256 attribute
boolean allowMetaRedirects
;
259 * Attribute stating if it should allow subframes (framesets/iframes) or not
261 attribute
boolean allowSubframes
;
264 * Attribute stating whether or not images should be loaded.
266 attribute
boolean allowImages
;
269 * Attribute that determines whether DNS prefetch is allowed for this subtree
270 * of the docshell tree. Defaults to true. Setting this will make it take
271 * effect starting with the next document loaded in the docshell.
273 attribute
boolean allowDNSPrefetch
;
276 * Get an enumerator over this docShell and its children.
278 * @param aItemType - Only include docShells of this type, or if typeAll,
279 * include all child shells.
280 * Uses types from nsIDocShellTreeItem.
281 * @param aDirection - Whether to enumerate forwards or backwards.
284 const long ENUMERATE_FORWARDS
= 0;
285 const long ENUMERATE_BACKWARDS
= 1;
287 nsISimpleEnumerator getDocShellEnumerator
(in long aItemType
,
291 * The type of application that created this window
293 const unsigned long APP_TYPE_UNKNOWN
= 0;
294 const unsigned long APP_TYPE_MAIL
= 1;
295 const unsigned long APP_TYPE_EDITOR
= 2;
297 attribute
unsigned long appType
;
300 * certain dochshells (like the message pane)
301 * should not throw up auth dialogs
302 * because it can act as a password trojan
304 attribute
boolean allowAuth
;
307 * Set/Get the document scale factor. When setting this attribute, a
308 * NS_ERROR_NOT_IMPLEMENTED error may be returned by implementations
309 * not supporting zoom. Implementations not supporting zoom should return
310 * 1.0 all the time for the Get operation. 1.0 by the way is the default
311 * of zoom. This means 100% of normal scaling or in other words normal size
314 attribute
float zoom
;
317 * The size, in CSS pixels, of the horizontal margins for the <body> of an
318 * HTML document in this docshel; used to implement the marginwidth attribute
319 * on HTML <frame>/<iframe> elements. A value smaller than zero indicates
320 * that the attribute was not set.
322 attribute
long marginWidth
;
325 * The size, in CSS pixels, of the vertical margins for the <body> of an HTML
326 * document in this docshel; used to implement the marginheight attribute on
327 * HTML <frame>/<iframe> elements. A value smaller than zero indicates that
328 * the attribute was not set.
330 attribute
long marginHeight
;
333 * Tells the docshell to offer focus to its tree owner.
334 * This is currently only necessary for embedding chrome.
336 void tabToTreeOwner
(in boolean forward
,
337 out boolean tookFocus
);
340 * Current busy state for DocShell
342 const unsigned long BUSY_FLAGS_NONE
= 0;
343 const unsigned long BUSY_FLAGS_BUSY
= 1;
344 const unsigned long BUSY_FLAGS_BEFORE_PAGE_LOAD
= 2;
345 const unsigned long BUSY_FLAGS_PAGE_LOADING
= 4;
348 * Load commands for the document
350 const unsigned long LOAD_CMD_NORMAL
= 0x1; // Normal load
351 const unsigned long LOAD_CMD_RELOAD
= 0x2; // Reload
352 const unsigned long LOAD_CMD_HISTORY
= 0x4; // Load from history
353 const unsigned long LOAD_CMD_PUSHSTATE
= 0x8; // History.pushState()
355 readonly attribute
unsigned long busyFlags
;
358 * attribute to access the loadtype for the document
360 attribute
unsigned long loadType
;
363 * returns true if the docshell is being destroyed, false otherwise
365 boolean isBeingDestroyed
();
368 * Returns true if the docshell is currently executing the onLoad Handler
370 readonly attribute
boolean isExecutingOnLoadHandler
;
372 attribute nsILayoutHistoryState layoutHistoryState
;
374 readonly attribute
boolean shouldSaveLayoutState
;
377 * The SecureBrowserUI object for this docshell. This is set by XUL
378 * <browser> or nsWebBrowser for their root docshell.
380 attribute nsISecureBrowserUI securityUI
;
383 * Cancel the XPCOM timers for each meta-refresh URI in this docshell,
384 * and this docshell's children, recursively. The meta-refresh timers can be
385 * restarted using resumeRefreshURIs(). If the timers are already suspended,
386 * this has no effect.
388 void suspendRefreshURIs
();
391 * Restart the XPCOM timers for each meta-refresh URI in this docshell,
392 * and this docshell's children, recursively. If the timers are already
393 * running, this has no effect.
395 void resumeRefreshURIs
();
398 * Begin firing WebProgressListener notifications for restoring a page
399 * presentation. |viewer| is the content viewer whose document we are
400 * starting to load. If null, it defaults to the docshell's current content
401 * viewer, creating one if necessary. |top| should be true for the toplevel
402 * docshell that is being restored; it will be set to false when this method
403 * is called for child docshells. This method will post an event to
404 * complete the simulated load after returning to the event loop.
406 void beginRestore
(in nsIContentViewer viewer
, in boolean top
);
409 * Finish firing WebProgressListener notifications and DOM events for
410 * restoring a page presentation. This should only be called via
413 void finishRestore
();
415 /* Track whether we're currently restoring a document presentation. */
416 readonly attribute
boolean restoringDocument
;
418 /* attribute to access whether error pages are enabled */
419 attribute
boolean useErrorPages
;
422 * Keeps track of the previous SHTransaction index and the current
423 * SHTransaction index at the time that the doc shell begins to load.
424 * Used for ContentViewer eviction.
426 readonly attribute
long previousTransIndex
;
427 readonly attribute
long loadedTransIndex
;
430 * Notification that entries have been removed from the beginning of a
431 * nsSHistory which has this as its rootDocShell.
433 * @param numEntries - The number of entries removed
435 void historyPurged
(in long numEntries
);
438 * Retrieves the WebApps session storage object for the supplied domain.
439 * If it doesn't already exist, a new one will be created.
441 * @param uri the uri of the storage object to retrieve
442 * @param documentURI new storage will be created with reference to this
443 * document.documentURI that will appear in storage event
445 nsIDOMStorage getSessionStorageForURI
(in nsIURI uri
,
446 in DOMString documentURI
);
449 * Retrieves the WebApps session storage object for the supplied principal.
451 * @param principal returns a storage for this principal
452 * @param documentURI new storage will be created with reference to this
453 * document.documentURI that will appear in storage event
454 * @param create If true and a session storage object doesn't
455 * already exist, a new one will be created.
457 nsIDOMStorage getSessionStorageForPrincipal
(in nsIPrincipal principal
,
458 in DOMString documentURI
,
462 * Add a WebApps session storage object to the docshell.
464 * @param principal the principal the storage object is associated with
465 * @param storage the storage object to add
467 void addSessionStorage
(in nsIPrincipal principal
, in nsIDOMStorage storage
);
470 * Gets the channel for the currently loaded document, if any.
471 * For a new document load, this will be the channel of the previous document
472 * until after OnLocationChange fires.
474 readonly attribute nsIChannel currentDocumentChannel
;
477 * Set the offset of this child in its container.
479 [noscript
] void setChildOffset
(in unsigned long offset
);
482 * Find out whether the docshell is currently in the middle of a page
483 * transition. This is set just before the pagehide/unload events fire.
485 readonly attribute
boolean isInUnload
;
488 * Find out if the currently loaded document came from a suspicious channel
489 * (such as a JAR channel where the server-returned content type isn't a
492 readonly attribute
boolean channelIsUnsafe
;
495 * Disconnects this docshell's editor from its window, and stores the
496 * editor data in the open document's session history entry. This
497 * should be called only during page transitions.
499 [noscript
, notxpcom
] void DetachEditorFromWindow
();
502 * If true, this browser is not visible in the traditional sense, but
503 * is actively being rendered to the screen (ex. painted on a canvas)
504 * and should be treated accordingly.
506 attribute
boolean isOffScreenBrowser
;
509 * If the current content viewer isn't initialized for print preview,
510 * it is replaced with one which is and to which an about:blank document
513 readonly attribute nsIWebBrowserPrint printPreview
;
516 * Whether this docshell can execute scripts based on its hierarchy.
517 * The rule of thumb here is that we disable js if this docshell or any
518 * of its parents disallow scripting, unless the only reason for js being
519 * disabled in this docshell is a parent docshell having a document that
520 * is in design mode. In that case, we explicitly allow scripting on the
523 readonly attribute
boolean canExecuteScripts
;
526 * Sets whether a docshell is active. An active docshell is one that is
527 * visible, and thus is not a good candidate for certain optimizations
528 * like image frame discarding. Docshells are active unless told otherwise.
530 attribute
boolean isActive
;
533 * The ID of the docshell in the session history.
535 readonly attribute
unsigned long long historyID
;
538 * Sets whether a docshell is an app tab. An app tab docshell may behave
539 * differently than a non-app tab docshell in some cases, such as when
540 * handling link clicks. Docshells are not app tabs unless told otherwise.
542 attribute
boolean isAppTab
;
545 [uuid(5f7a2184
-31b6
-4d67
-9c75
-0c17477766e2
)]
546 interface nsIDocShell_MOZILLA_2_0_BRANCH
: nsISupports
{
548 * Create a new about:blank document and content viewer.
549 * @param aPrincipal the principal to use for the new document.
551 void createAboutBlankContentViewer
(in nsIPrincipal aPrincipal
);