docshell/base/nsIDocShell.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   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/
  10  *
  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
  14  * License.
  15  *
  16  * The Original Code is the Mozilla browser.
  17  *
  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.
  22  *
  23  * Contributor(s):
  24  *   Travis Bogard <travis@netscape.com>
  25  *   Steve Clark <buster@netscape.com>
  26  *
  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.
  38  *
  39  * ***** END LICENSE BLOCK ***** */
  40
  41 #include "nsISupports.idl"
  42
  43 %{ C++
  44 class nsPresContext;
  45 class nsIPresShell;
  46 %}
  47
  48 /**
  49  * The nsIDocShell interface.
  50  */
  51
  52 [ptr] native nsPresContext(nsPresContext);
  53 [ptr] native nsIPresShell(nsIPresShell);
  54
  55 interface nsIURI;
  56 interface nsIChannel;
  57 interface nsIContentViewer;
  58 interface nsIURIContentListener;
  59 interface nsIDOMEventTarget;
  60 interface nsIDocShellLoadInfo;
  61 interface nsIDocumentCharsetInfo;
  62 interface nsIWebNavigation;
  63 interface nsISimpleEnumerator;
  64 interface nsIInputStream;
  65 interface nsIRequest;
  66 interface nsISHEntry;
  67 interface nsILayoutHistoryState;
  68 interface nsISecureBrowserUI;
  69 interface nsIDOMStorage;
  70
  71 [scriptable, uuid(7d1cf6b9-daa3-476d-8f9f-9eb2a971a95c)]
  72 interface nsIDocShell : nsISupports
  73 {
  74   /**
  75    * Loads a given URI.  This will give priority to loading the requested URI
  76    * in the object implementing this interface.  If it can't be loaded here
  77    * however, the URL dispatcher will go through its normal process of content
  78    * loading.
  79    *
  80    * @param uri        - The URI to load.
  81    * @param loadInfo   - This is the extended load info for this load.  This
  82    *                     most often will be null, but if you need to do
  83    *                     additional setup for this load you can get a loadInfo
  84    *                     object by calling createLoadInfo.  Once you have this
  85    *                     object you can set the needed properties on it and
  86    *                     then pass it to loadURI.
  87    * @param aLoadFlags - Flags to modify load behaviour. Flags are defined
  88    *                     in nsIWebNavigation.
  89    */
  90   [noscript]void loadURI(in nsIURI uri,
  91                          in nsIDocShellLoadInfo loadInfo,
  92                          in unsigned long aLoadFlags,
  93                          in boolean firstParty);
  94
  95   /**
  96    * Loads a given stream. This will give priority to loading the requested
  97    * stream in the object implementing this interface. If it can't be loaded
  98    * here however, the URL dispatched will go through its normal process of
  99    * content loading.
 100    *
 101    * @param aStream         - The input stream that provides access to the data
 102    *                          to be loaded.  This must be a blocking, threadsafe
 103    *                          stream implementation.
 104    * @param aURI            - The URI representing the stream, or null.
 105    * @param aContentType    - The type (MIME) of data being loaded (empty if unknown).
 106    * @param aContentCharset - The charset of the data being loaded (empty if unknown).
 107    * @param aLoadInfo       - This is the extended load info for this load.  This
 108    *                          most often will be null, but if you need to do
 109    *                          additional setup for this load you can get a
 110    *                          loadInfo object by calling createLoadInfo.  Once
 111    *                          you have this object you can set the needed
 112    *                          properties on it and then pass it to loadStream.
 113    */
 114   [noscript]void loadStream(in nsIInputStream aStream,
 115                             in nsIURI aURI,
 116                             in ACString aContentType,
 117                             in ACString aContentCharset,
 118                             in nsIDocShellLoadInfo aLoadInfo);
 119
 120   const long INTERNAL_LOAD_FLAGS_NONE                    = 0x0;
 121   const long INTERNAL_LOAD_FLAGS_INHERIT_OWNER           = 0x1;
 122   const long INTERNAL_LOAD_FLAGS_DONT_SEND_REFERRER      = 0x2;
 123   const long INTERNAL_LOAD_FLAGS_ALLOW_THIRD_PARTY_FIXUP = 0x4;
 124
 125   // This flag marks the first load in this object
 126   // @see nsIWebNavigation::LOAD_FLAGS_FIRST_LOAD
 127   const long INTERNAL_LOAD_FLAGS_FIRST_LOAD              = 0x8;
 128
 129   const long INTERNAL_LOAD_FLAGS_BYPASS_CLASSIFIER       = 0x10;
 130
 131   /**
 132    * Loads the given URI.  This method is identical to loadURI(...) except
 133    * that its parameter list is broken out instead of being packaged inside
 134    * of an nsIDocShellLoadInfo object...
 135    *
 136    * @param aURI            - The URI to load.
 137    * @param aReferrer       - Referring URI
 138    * @param aOwner          - Owner (security principal)
 139    * @param aInheritOwner   - Flag indicating whether the owner of the current
 140    *                          document should be inherited if aOwner is null.
 141    * @param aStopActiveDoc  - Flag indicating whether loading the current
 142    *                          document should be stopped.
 143    * @param aWindowTarget   - Window target for the load.
 144    * @param aTypeHint       - A hint as to the content-type of the resulting
 145    *                          data.  May be null or empty if no hint.
 146    * @param aPostDataStream - Post data stream (if POSTing)
 147    * @param aHeadersStream  - Stream containing "extra" request headers...
 148    * @param aLoadFlags      - Flags to modify load behaviour. Flags are defined
 149    *                          in nsIWebNavigation.
 150    * @param aSHEntry        - Active Session History entry (if loading from SH)
 151    */
 152   [noscript]void internalLoad(in nsIURI aURI,
 153                               in nsIURI aReferrer,
 154                               in nsISupports aOwner,
 155                               in PRUint32 aFlags,
 156                               in wstring aWindowTarget,
 157                               in string aTypeHint,
 158                               in nsIInputStream aPostDataStream,
 159                               in nsIInputStream aHeadersStream,
 160                               in unsigned long aLoadFlags,
 161                               in nsISHEntry aSHEntry,
 162                               in boolean firstParty,
 163                               out nsIDocShell aDocShell,
 164                               out nsIRequest aRequest);
 165
 166   /**
 167    * Creates a DocShellLoadInfo object that you can manipulate and then pass
 168    * to loadURI.
 169    */
 170   void createLoadInfo(out nsIDocShellLoadInfo loadInfo);
 171
 172   /**
 173    * Reset state to a new content model within the current document and the document
 174    * viewer.  Called by the document before initiating an out of band document.write().
 175    */
 176   void prepareForNewContentModel();
 177
 178   /**
 179    * For editors and suchlike who wish to change the URI associated with the
 180    * document. Note if you want to get the current URI, use the read-only
 181    * property on nsIWebNavigation.
 182    */
 183   void setCurrentURI(in nsIURI aURI);
 184
 185   /**
 186    * Notify the associated content viewer and all child docshells that they are
 187    * about to be hidden.  If |isUnload| is true, then the document is being
 188    * unloaded as well.
 189    *
 190    * @param isUnload if true, fire the unload event in addition to the pagehide
 191    *                 event.
 192    */
 193   [noscript] void firePageHideNotification(in boolean isUnload);
 194
 195   /**
 196    * Presentation context for the currently loaded document.  This may be null.
 197    */
 198   [noscript] readonly attribute nsPresContext presContext;
 199
 200   /**
 201    * Presentation shell for the currently loaded document.  This may be null.
 202    */
 203   [noscript] readonly attribute nsIPresShell presShell;
 204
 205   /**
 206    * Presentation shell for the oldest document, if this docshell is
 207    * currently transitioning between documents.
 208    */
 209   [noscript] readonly attribute nsIPresShell eldestPresShell;
 210
 211   /**
 212    * Content Viewer that is currently loaded for this DocShell.  This may
 213    * change as the underlying content changes.
 214    */
 215   readonly attribute nsIContentViewer contentViewer;
 216
 217   /**
 218    * This attribute allows chrome to tie in to handle DOM events that may
 219    * be of interest to chrome.
 220    */
 221   attribute nsIDOMEventTarget chromeEventHandler;
 222
 223   /**
 224    * The document charset info.  This is used by a load to determine priorities
 225    * for charset detection etc.
 226    */
 227   attribute nsIDocumentCharsetInfo documentCharsetInfo;
 228
 229   /**
 230    * Whether to allow plugin execution
 231    */
 232   attribute boolean allowPlugins;
 233
 234   /**
 235    * Whether to allow Javascript execution
 236    */
 237   attribute boolean allowJavascript;
 238
 239   /**
 240    * Attribute stating if refresh based redirects can be allowed
 241    */
 242   attribute  boolean allowMetaRedirects;
 243
 244   /**
 245    * Attribute stating if it should allow subframes (framesets/iframes) or not
 246    */
 247   attribute boolean allowSubframes;
 248
 249   /**
 250    * Attribute stating whether or not images should be loaded.
 251    */
 252   attribute boolean allowImages;
 253
 254   /**
 255    * Get an enumerator over this docShell and its children.
 256    *
 257    * @param aItemType  - Only include docShells of this type, or if typeAll,
 258    *                     include all child shells.
 259    *                     Uses types from nsIDocShellTreeItem.
 260    * @param aDirection - Whether to enumerate forwards or backwards.
 261    */
 262
 263   const long ENUMERATE_FORWARDS  = 0;
 264   const long ENUMERATE_BACKWARDS = 1;
 265
 266   nsISimpleEnumerator getDocShellEnumerator(in long aItemType,
 267                                             in long aDirection);
 268
 269   /**
 270    * The type of application that created this window
 271    */
 272   const unsigned long APP_TYPE_UNKNOWN  = 0;
 273   const unsigned long APP_TYPE_MAIL     = 1;
 274   const unsigned long APP_TYPE_EDITOR   = 2;
 275
 276   attribute unsigned long appType;
 277
 278   /**
 279    * certain dochshells (like the message pane)
 280    * should not throw up auth dialogs
 281    * because it can act as a password trojan
 282    */
 283   attribute boolean allowAuth;
 284
 285   /**
 286    * Set/Get the document scale factor.  When setting this attribute, a
 287    * NS_ERROR_NOT_IMPLEMENTED error may be returned by implementations
 288    * not supporting zoom.  Implementations not supporting zoom should return
 289    * 1.0 all the time for the Get operation.  1.0 by the way is the default
 290    * of zoom.  This means 100% of normal scaling or in other words normal size
 291    * no zoom.
 292    */
 293   attribute float zoom;
 294
 295   /*
 296    * XXX Comment here!
 297    */
 298   attribute long marginWidth;
 299
 300   /*
 301    * XXX Comment here!
 302    */
 303   attribute long marginHeight;
 304
 305   /*
 306    * Tells the DocShell that it now has focus or has lost focus
 307    */
 308   attribute boolean hasFocus;
 309
 310   /*
 311    * Tells the docshell whether the canvas should have focus
 312    */
 313   attribute boolean canvasHasFocus;
 314
 315   /*
 316    * Tells the docshell to offer focus to its tree owner.
 317    * This is currently only necessary for embedding chrome.
 318    */
 319   void tabToTreeOwner(in boolean forward,
 320                       out boolean tookFocus);
 321
 322   /**
 323    * Current busy state for DocShell
 324    */
 325   const unsigned long BUSY_FLAGS_NONE             = 0;
 326   const unsigned long BUSY_FLAGS_BUSY             = 1;
 327   const unsigned long BUSY_FLAGS_BEFORE_PAGE_LOAD = 2;
 328   const unsigned long BUSY_FLAGS_PAGE_LOADING     = 4;
 329
 330   /**
 331    * Load commands for the document
 332    */
 333   const unsigned long LOAD_CMD_NORMAL  = 0x1; // Normal load
 334   const unsigned long LOAD_CMD_RELOAD  = 0x2; // Reload
 335   const unsigned long LOAD_CMD_HISTORY = 0x4; // Load from history
 336
 337   readonly attribute unsigned long busyFlags;
 338
 339   /*
 340    * attribute to access the loadtype  for the document
 341    */
 342   attribute unsigned long  loadType;
 343
 344   /*
 345    * returns true if the docshell is being destroyed, false otherwise
 346    */
 347   boolean isBeingDestroyed();
 348
 349   /*
 350    * Returns true if the docshell is currently executing the onLoad Handler
 351    */
 352   readonly attribute boolean isExecutingOnLoadHandler;
 353
 354   attribute nsILayoutHistoryState layoutHistoryState;
 355
 356   readonly attribute boolean shouldSaveLayoutState;
 357
 358   /**
 359    * The SecureBrowserUI object for this docshell.  This is set by XUL
 360    * <browser> or nsWebBrowser for their root docshell.
 361    */
 362   attribute nsISecureBrowserUI securityUI;
 363
 364   /**
 365    * Cancel the XPCOM timers for each meta-refresh URI in this docshell,
 366    * and this docshell's children, recursively. The meta-refresh timers can be
 367    * restarted using resumeRefreshURIs().  If the timers are already suspended,
 368    * this has no effect.
 369    */
 370   void suspendRefreshURIs();
 371
 372   /**
 373    * Restart the XPCOM timers for each meta-refresh URI in this docshell,
 374    * and this docshell's children, recursively.  If the timers are already
 375    * running, this has no effect.
 376    */
 377   void resumeRefreshURIs();
 378
 379   /**
 380    * Begin firing WebProgressListener notifications for restoring a page
 381    * presentation. |viewer| is the content viewer whose document we are
 382    * starting to load.  If null, it defaults to the docshell's current content
 383    * viewer, creating one if necessary.  |top| should be true for the toplevel
 384    * docshell that is being restored; it will be set to false when this method
 385    * is called for child docshells.  This method will post an event to
 386    * complete the simulated load after returning to the event loop.
 387    */
 388   void beginRestore(in nsIContentViewer viewer, in boolean top);
 389
 390   /**
 391    * Finish firing WebProgressListener notifications and DOM events for
 392    * restoring a page presentation.  This should only be called via
 393    * beginRestore().
 394    */
 395   void finishRestore();
 396
 397   /* Track whether we're currently restoring a document presentation. */
 398   readonly attribute boolean restoringDocument;
 399
 400   /* attribute to access whether error pages are enabled */
 401   attribute boolean useErrorPages;
 402
 403   /**
 404    * Keeps track of the previous SHTransaction index and the current
 405    * SHTransaction index at the time that the doc shell begins to load.
 406    * Used for ContentViewer eviction.
 407    */
 408   readonly attribute long previousTransIndex;
 409   readonly attribute long loadedTransIndex;
 410
 411   /**
 412    * Notification that entries have been removed from the beginning of a
 413    * nsSHistory which has this as its rootDocShell.
 414    *
 415    * @param numEntries - The number of entries removed
 416    */
 417   void historyPurged(in long numEntries);
 418
 419   /*
 420    * Retrieves the WebApps session storage object for the supplied domain.
 421    * If it doesn't already exist, a new one will be created.
 422    *
 423    * @param domain the domain of the storage object to retrieve
 424    */
 425   nsIDOMStorage getSessionStorageForURI(in nsIURI uri);
 426
 427   /*
 428    * Add a WebApps session storage object to the docshell.
 429    *
 430    * @param domain the domain the storage object is associated with
 431    * @param storage the storage object to add
 432    */
 433   void addSessionStorage(in ACString aDomain, in nsIDOMStorage storage);
 434
 435   /**
 436    * Gets the channel for the currently loaded document, if any.
 437    * For a new document load, this will be the channel of the previous document
 438    * until after OnLocationChange fires.
 439    */
 440   readonly attribute nsIChannel currentDocumentChannel;
 441
 442   /**
 443    * Set the offset of this child in its container.
 444    */
 445   [noscript] void setChildOffset(in unsigned long offset);
 446
 447   /**
 448    * Find out whether the docshell is currently in the middle of a page
 449    * transition (after the onunload event has fired, but before the new
 450    * document has been set up)
 451    */
 452   readonly attribute boolean isInUnload;
 453
 454   /**
 455    * Find out if the currently loaded document came from a suspicious channel
 456    * (such as a JAR channel where the server-returned content type isn't a
 457    * known JAR type).
 458    */
 459   readonly attribute boolean channelIsUnsafe;
 460
 461   /**
 462    * Disconnects this docshell's editor from its window, and stores the
 463    * editor data in the open document's session history entry.
 464    */
 465   [noscript, notxpcom] void DetachEditorFromWindow();
 466 };
 467