nsIDocShell.idl

/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
#include "nsIAtom.idl"

%{ C++
class nsPresContext;
class nsIPresShell;
struct JSContext;
%}

/**
 * The nsIDocShell interface.
 */

[ptr] native nsPresContext(nsPresContext);
[ptr] native nsIPresShell(nsIPresShell);

interface nsIURI;
interface nsIChannel;
interface nsIContentViewer;
interface nsIURIContentListener;
interface nsIDOMEventTarget;
interface nsIDocShellLoadInfo;
interface nsIWebNavigation;
interface nsISimpleEnumerator;
interface nsIInputStream;
interface nsIRequest;
interface nsISHEntry;
interface nsILayoutHistoryState;
interface nsISecureBrowserUI;
interface nsIDOMStorage;
interface nsIPrincipal;
interface nsIWebBrowserPrint;
interface nsIVariant;
interface nsIPrivacyTransitionObserver;

[scriptable, builtinclass, uuid(318CE516-3F7A-41F6-8F3D-3661650F7A46)]
interface nsIDocShell : nsISupports
{
  /**
   * Loads a given URI.  This will give priority to loading the requested URI
   * in the object implementing	this interface.  If it can't be loaded here
   * however, the URL dispatcher will go through its normal process of content
   * loading.
   *
   * @param uri        - The URI to load.
   * @param loadInfo   - This is the extended load info for this load.  This
   *                     most often will be null, but if you need to do 
   *                     additional setup for this load you can get a loadInfo
   *                     object by calling createLoadInfo.  Once you have this
   *                     object you can set the needed properties on it and
   *                     then pass it to loadURI.
   * @param aLoadFlags - Flags to modify load behaviour. Flags are defined in
   *                     nsIWebNavigation.  Note that using flags outside
   *                     LOAD_FLAGS_MASK is only allowed if passing in a
   *                     non-null loadInfo.  And even some of those might not
   *                     be allowed.  Use at your own risk.
   */
  [noscript]void loadURI(in nsIURI uri,
                         in nsIDocShellLoadInfo loadInfo,
                         in unsigned long aLoadFlags,
                         in boolean firstParty);

  /**
   * Loads a given stream. This will give priority to loading the requested
   * stream in the object implementing this interface. If it can't be loaded
   * here however, the URL dispatched will go through its normal process of
   * content loading.
   *
   * @param aStream         - The input stream that provides access to the data
   *                          to be loaded.  This must be a blocking, threadsafe
   *                          stream implementation.
   * @param aURI            - The URI representing the stream, or null.
   * @param aContentType    - The type (MIME) of data being loaded (empty if unknown).
   * @param aContentCharset - The charset of the data being loaded (empty if unknown).
   * @param aLoadInfo       - This is the extended load info for this load.  This
   *                          most often will be null, but if you need to do 
   *                          additional setup for this load you can get a
   *                          loadInfo object by calling createLoadInfo.  Once
   *                          you have this object you can set the needed 
   *                          properties on it and then pass it to loadStream.
   */
  [noscript]void loadStream(in nsIInputStream aStream,
                            in nsIURI aURI,
                            in ACString aContentType,
                            in ACString aContentCharset,
                            in nsIDocShellLoadInfo aLoadInfo);

  const long INTERNAL_LOAD_FLAGS_NONE                    = 0x0;
  const long INTERNAL_LOAD_FLAGS_INHERIT_OWNER           = 0x1;
  const long INTERNAL_LOAD_FLAGS_DONT_SEND_REFERRER      = 0x2;
  const long INTERNAL_LOAD_FLAGS_ALLOW_THIRD_PARTY_FIXUP = 0x4;

  // This flag marks the first load in this object
  // @see nsIWebNavigation::LOAD_FLAGS_FIRST_LOAD
  const long INTERNAL_LOAD_FLAGS_FIRST_LOAD              = 0x8;

  const long INTERNAL_LOAD_FLAGS_BYPASS_CLASSIFIER       = 0x10;
  const long INTERNAL_LOAD_FLAGS_FORCE_ALLOW_COOKIES     = 0x20;

  /**
   * Loads the given URI.  This method is identical to loadURI(...) except
   * that its parameter list is broken out instead of being packaged inside
   * of an nsIDocShellLoadInfo object...
   *
   * @param aURI            - The URI to load.
   * @param aReferrer       - Referring URI
   * @param aOwner          - Owner (security principal) 
   * @param aInheritOwner   - Flag indicating whether the owner of the current
   *                          document should be inherited if aOwner is null.
   * @param aStopActiveDoc  - Flag indicating whether loading the current
   *                          document should be stopped.
   * @param aWindowTarget   - Window target for the load.
   * @param aTypeHint       - A hint as to the content-type of the resulting
   *                          data.  May be null or empty if no hint.
   * @param aPostDataStream - Post data stream (if POSTing)
   * @param aHeadersStream  - Stream containing "extra" request headers...
   * @param aLoadFlags      - Flags to modify load behaviour. Flags are defined
   *                          in nsIWebNavigation.
   * @param aSHEntry        - Active Session History entry (if loading from SH)
   */
  [noscript]void internalLoad(in nsIURI aURI,
                              in nsIURI aReferrer,
                              in nsISupports aOwner,
                              in uint32_t aFlags,
                              in wstring aWindowTarget,
                              in string aTypeHint,
                              in nsIInputStream aPostDataStream,
                              in nsIInputStream aHeadersStream,
                              in unsigned long aLoadFlags,
                              in nsISHEntry aSHEntry,
                              in boolean firstParty,
                              out nsIDocShell aDocShell,
                              out nsIRequest aRequest);

  /**
   * Do either a history.pushState() or history.replaceState() operation,
   * depending on the value of aReplace.
   */
  [implicit_jscontext]
  void addState(in nsIVariant aData, in DOMString aTitle,
                in DOMString aURL, in boolean aReplace);

  /**
   * Creates a DocShellLoadInfo object that you can manipulate and then pass
   * to loadURI.
   */
  void createLoadInfo(out nsIDocShellLoadInfo loadInfo);

  /**
   * Reset state to a new content model within the current document and the document
   * viewer.  Called by the document before initiating an out of band document.write().
   */
  void prepareForNewContentModel();

  /**
   * For editors and suchlike who wish to change the URI associated with the
   * document. Note if you want to get the current URI, use the read-only
   * property on nsIWebNavigation.
   */ 
  void setCurrentURI(in nsIURI aURI);

  /**
   * Notify the associated content viewer and all child docshells that they are
   * about to be hidden.  If |isUnload| is true, then the document is being
   * unloaded as well.
   *
   * @param isUnload if true, fire the unload event in addition to the pagehide
   *                 event.
   */
  [noscript] void firePageHideNotification(in boolean isUnload);

  /**
   * Presentation context for the currently loaded document.  This may be null.
   */
  [noscript] readonly attribute nsPresContext presContext;

  /**
   * Presentation shell for the currently loaded document.  This may be null.
   */
  [noscript] readonly attribute nsIPresShell presShell;

  /**
   * Presentation shell for the oldest document, if this docshell is
   * currently transitioning between documents.
   */
  [noscript] readonly attribute nsIPresShell eldestPresShell;

  /**
   * Content Viewer that is currently loaded for this DocShell.  This may
   * change as the underlying content changes.
   */
  readonly attribute nsIContentViewer contentViewer;

  /**
   * This attribute allows chrome to tie in to handle DOM events that may
   * be of interest to chrome.
   */
  attribute nsIDOMEventTarget chromeEventHandler;

  /**
   * Whether to allow plugin execution
   */
  attribute boolean allowPlugins;

  /**
   * Whether to allow Javascript execution
   */
  attribute boolean allowJavascript;

  /**
   * Attribute stating if refresh based redirects can be allowed
   */
  attribute  boolean allowMetaRedirects;

  /**
   * Attribute stating if it should allow subframes (framesets/iframes) or not
   */
  attribute boolean allowSubframes;

  /**
   * Attribute stating whether or not images should be loaded.
   */
  attribute boolean allowImages;

  /**
   * Attribute that determines whether DNS prefetch is allowed for this subtree
   * of the docshell tree.  Defaults to true.  Setting this will make it take
   * effect starting with the next document loaded in the docshell.
   */
  attribute boolean allowDNSPrefetch;

  /**
   * Attribute that determines whether window control (move/resize) is allowed.
   */
  attribute boolean allowWindowControl;

  /**
   * Get an enumerator over this docShell and its children.
   *
   * @param aItemType  - Only include docShells of this type, or if typeAll,
   *                     include all child shells.
   *                     Uses types from nsIDocShellTreeItem.
   * @param aDirection - Whether to enumerate forwards or backwards.
   */

  const long ENUMERATE_FORWARDS  = 0;
  const long ENUMERATE_BACKWARDS = 1;

  nsISimpleEnumerator getDocShellEnumerator(in long aItemType,
                                            in long aDirection);

  /**
   * The type of application that created this window
   */
  const unsigned long APP_TYPE_UNKNOWN  = 0;
  const unsigned long APP_TYPE_MAIL     = 1;
  const unsigned long APP_TYPE_EDITOR   = 2;

  attribute unsigned long appType;

  /**
   * certain dochshells (like the message pane)
   * should not throw up auth dialogs
   * because it can act as a password trojan
   */
  attribute boolean allowAuth;

  /**
   * Set/Get the document scale factor.  When setting this attribute, a
   * NS_ERROR_NOT_IMPLEMENTED error may be returned by implementations
   * not supporting zoom.  Implementations not supporting zoom should return
   * 1.0 all the time for the Get operation.  1.0 by the way is the default
   * of zoom.  This means 100% of normal scaling or in other words normal size
   * no zoom. 
   */
  attribute float zoom;

  /*
   * The size, in CSS pixels, of the horizontal margins for the <body> of an
   * HTML document in this docshel; used to implement the marginwidth attribute
   * on HTML <frame>/<iframe> elements.  A value smaller than zero indicates
   * that the attribute was not set.
   */
  attribute long marginWidth;

  /*
   * The size, in CSS pixels, of the vertical margins for the <body> of an HTML
   * document in this docshel; used to implement the marginheight attribute on
   * HTML <frame>/<iframe> elements.  A value smaller than zero indicates that
   * the attribute was not set.
   */
  attribute long marginHeight;

  /*
   * Tells the docshell to offer focus to its tree owner.
   * This is currently only necessary for embedding chrome.
   */
  void tabToTreeOwner(in boolean forward,
                      out boolean tookFocus);

  /**
   * Current busy state for DocShell
   */
  const unsigned long BUSY_FLAGS_NONE             = 0;
  const unsigned long BUSY_FLAGS_BUSY             = 1;
  const unsigned long BUSY_FLAGS_BEFORE_PAGE_LOAD = 2;
  const unsigned long BUSY_FLAGS_PAGE_LOADING     = 4;

  /**
   * Load commands for the document 
   */
  const unsigned long LOAD_CMD_NORMAL  = 0x1;   // Normal load
  const unsigned long LOAD_CMD_RELOAD  = 0x2;   // Reload
  const unsigned long LOAD_CMD_HISTORY = 0x4;   // Load from history
  const unsigned long LOAD_CMD_PUSHSTATE = 0x8; // History.pushState()

  readonly attribute unsigned long busyFlags;

  /* 
   * attribute to access the loadtype  for the document
   */
  attribute unsigned long  loadType;

  /*
   * returns true if the docshell is being destroyed, false otherwise
   */
  boolean isBeingDestroyed();

  /*
   * Returns true if the docshell is currently executing the onLoad Handler
   */
  readonly attribute boolean isExecutingOnLoadHandler;

  attribute nsILayoutHistoryState layoutHistoryState;

  readonly attribute boolean shouldSaveLayoutState;

  /**
   * The SecureBrowserUI object for this docshell.  This is set by XUL
   * <browser> or nsWebBrowser for their root docshell.
   */
  attribute nsISecureBrowserUI securityUI;

  /**
   * Cancel the XPCOM timers for each meta-refresh URI in this docshell,
   * and this docshell's children, recursively. The meta-refresh timers can be
   * restarted using resumeRefreshURIs().  If the timers are already suspended,
   * this has no effect.
   */
  void suspendRefreshURIs();

  /**
   * Restart the XPCOM timers for each meta-refresh URI in this docshell,
   * and this docshell's children, recursively.  If the timers are already
   * running, this has no effect.
   */
  void resumeRefreshURIs();

  /**
   * Begin firing WebProgressListener notifications for restoring a page
   * presentation. |viewer| is the content viewer whose document we are
   * starting to load.  If null, it defaults to the docshell's current content
   * viewer, creating one if necessary.  |top| should be true for the toplevel
   * docshell that is being restored; it will be set to false when this method
   * is called for child docshells.  This method will post an event to
   * complete the simulated load after returning to the event loop.
   */
  void beginRestore(in nsIContentViewer viewer, in boolean top);

  /**
   * Finish firing WebProgressListener notifications and DOM events for
   * restoring a page presentation.  This should only be called via
   * beginRestore().
   */
  void finishRestore();

  /* Track whether we're currently restoring a document presentation. */
  readonly attribute boolean restoringDocument;

  /* attribute to access whether error pages are enabled */
  attribute boolean useErrorPages;

  /**
   * Keeps track of the previous SHTransaction index and the current
   * SHTransaction index at the time that the doc shell begins to load.
   * Used for ContentViewer eviction.
   */
  readonly attribute long previousTransIndex;
  readonly attribute long loadedTransIndex;

  /**
   * Notification that entries have been removed from the beginning of a
   * nsSHistory which has this as its rootDocShell.
   *
   * @param numEntries - The number of entries removed
   */
  void historyPurged(in long numEntries);

  /*
   * Retrieves the WebApps session storage object for the supplied principal.
   *
   * @param principal returns a storage for this principal
   * @param documentURI new storage will be created with reference to this
   *                    document.documentURI that will appear in storage event
   * @param create If true and a session storage object doesn't
   *               already exist, a new one will be created.
   */
  nsIDOMStorage getSessionStorageForPrincipal(in nsIPrincipal principal,
                                              in DOMString documentURI,
                                              in boolean create);

  /*
   * Add a WebApps session storage object to the docshell.
   *
   * @param principal the principal the storage object is associated with
   * @param storage the storage object to add
   */
  void addSessionStorage(in nsIPrincipal principal, in nsIDOMStorage storage);

  /**
   * Clones all session storage objects and attaches them to the given docshell.
   * Useful when duplicating tabs and their states.
   *
   * @param docShell the docshell to clone the sessionstorage objects to
   */
  void cloneSessionStoragesTo(in nsIDocShell docShell);

  /**
   * Removes all WebApps session storage objects attached to the docshell.
   */
  void clearSessionStorages();

  /**
   * Gets the channel for the currently loaded document, if any. 
   * For a new document load, this will be the channel of the previous document
   * until after OnLocationChange fires.
   */
  readonly attribute nsIChannel currentDocumentChannel;

  /**
   * Set the offset of this child in its container.
   */
  [noscript] void setChildOffset(in unsigned long offset);

  /**
   * Find out whether the docshell is currently in the middle of a page
   * transition. This is set just before the pagehide/unload events fire.
   */
  readonly attribute boolean isInUnload;

  /**
   * Find out if the currently loaded document came from a suspicious channel
   * (such as a JAR channel where the server-returned content type isn't a
   * known JAR type).
   */
  readonly attribute boolean channelIsUnsafe;

  /**
   * Disconnects this docshell's editor from its window, and stores the
   * editor data in the open document's session history entry.  This
   * should be called only during page transitions.
   */
  [noscript, notxpcom] void DetachEditorFromWindow();

  /**
   * If true, this browser is not visible in the traditional sense, but
   * is actively being rendered to the screen (ex. painted on a canvas)
   * and should be treated accordingly.
   **/
  attribute boolean isOffScreenBrowser;    

  /**
   * If the current content viewer isn't initialized for print preview,
   * it is replaced with one which is and to which an about:blank document
   * is loaded.
   */
  readonly attribute nsIWebBrowserPrint printPreview;

  /**
   * Whether this docshell can execute scripts based on its hierarchy.
   * The rule of thumb here is that we disable js if this docshell or any
   * of its parents disallow scripting, unless the only reason for js being
   * disabled in this docshell is a parent docshell having a document that
   * is in design mode.  In that case, we explicitly allow scripting on the
   * current docshell.
   */
  readonly attribute boolean canExecuteScripts;

  /**
   * Sets whether a docshell is active. An active docshell is one that is
   * visible, and thus is not a good candidate for certain optimizations
   * like image frame discarding. Docshells are active unless told otherwise.
   */
  attribute boolean isActive;

  /**
   * The ID of the docshell in the session history.
   */
  readonly attribute unsigned long long historyID;

  /**
   * Sets whether a docshell is an app tab. An app tab docshell may behave
   * differently than a non-app tab docshell in some cases, such as when
   * handling link clicks. Docshells are not app tabs unless told otherwise.
   */
  attribute boolean isAppTab;

  /**
   * Create a new about:blank document and content viewer.
   * @param aPrincipal the principal to use for the new document.
   */
  void createAboutBlankContentViewer(in nsIPrincipal aPrincipal);

  /**
   * The charset attribute allows the user to view, hint, and set which
   * converter is used to read the document's data.
   *
   * <P>Inside Mozilla all text is encoded as Unicode. By standardizing  
   * on Unicode every piece of code that handles characters no longer 
   * needs to: 
   *
   *     Have access to a character encoding parameter.
   *     Ask is the data stateful?
   *     Ask is the data single byte?
   *     Ask is the data multi-byte?
   *     If multi-byte: have access to a routine that can
   *         determine how many bytes in the current character.
   *
   * When the document is read in a converter is used to convert 
   * the document's data to Unicode.
   *
   * The charset attribute provides the ability to:
   *
   *   See what converter was used when inputting the documents
   *   data.
   *
   *   Override the character set for documents where the specified 
   *   fallback, or auto-detected character set is incorrect
   *
   * Get/sets the encoding (converter) used to read the 
   * document. Get returns the encoding used. Set forces 
   * (overrides) the encoding. After forcing the charset the 
   * embedding application will need to cause the data to be 
   * reparsed in order to update the DOM / display.
   *
   * A force also sets the fallback encoding for this frame.
   */
  attribute string charset;

  /**
   * The charset forced by the user. When the charset attribute is set this
   * attribute is set to the same value.
   *
   * XXX Could this be replaced by a boolean?
   */
  attribute nsIAtom forcedCharset;

  /**
   * In a child docshell, this is the charset of the parent docshell
   */
  attribute nsIAtom parentCharset;

  /*
   * In a child docshell, this is the source of parentCharset
   * @see nsIParser
   */
  attribute int32_t parentCharsetSource;

  /**
   * Add an observer to the list of parties to be notified when this docshell's
   * private browsing status is changed. |obs| must support weak references.
   */
  void addWeakPrivacyTransitionObserver(in nsIPrivacyTransitionObserver obs);

  /**
   * Returns true if this docshell corresponds to an <iframe mozbrowser>.
   * (<iframe mozapp mozbrowser> is not considered a browser.)
   */
  [infallible] readonly attribute boolean isBrowserElement;

  /**
   * Returns true iff the docshell corresponds to an <iframe mozapp>.
   */
  [infallible] readonly attribute boolean isApp;

  /**
   * Returns isBrowserElement || isApp.
   */
  [infallible] readonly attribute boolean isBrowserOrApp;

  /**
   * Returns true if this docshell corresponds to an <iframe mozbrowser> or if
   * the docshell is contained in an <iframe mozbrowser>.  (<iframe mozapp
   * mozbrowser> does not count as a browser.)
   *
   * Our notion here of "contained in" means: Walk up the docshell hierarchy in
   * this process until we hit an <iframe mozapp> or <iframe mozbrowser> (or
   * until the hierarchy ends).  Return true iff the docshell we stopped on has
   * isBrowserElement == true.
   */
  [infallible] readonly attribute boolean isInBrowserElement;

  /**
   * Returns true if this docshell corresponds to an <iframe mozbrowser> or
   * <iframe mozap>, or if this docshell is contained in an <iframe mozbrowser>
   * or <iframe mozapp>.
   *
   * To compute this value, we walk up the docshell hierarchy.  If we encounter
   * a docshell with isBrowserElement or isApp before we hit the end of the
   * hierarchy, we return true.  Otherwise, we return false.
   */
  [infallible] readonly attribute boolean isInBrowserOrApp;

   /**
    * Indicate that this docshell corresponds to an app with the given app id.
    *
    * You may pass NO_APP_ID or UNKNOWN_APP_ID for containingAppId.  If you
    * pass NO_APP_ID, then this docshell will return NO_APP_ID for appId.  If
    * you pass UNKNOWN_APP_ID, then this docshell will search its hiearchy for
    * an app frame and use that frame's appId.
    *
    * You can call this method more than once, but there's no guarantee that
    * other components will update their view of the world if you change a
    * docshell's app id, so tread lightly.
    *
    * If you call this method after calling setIsBrowserInsideApp, this
    * docshell will forget the fact that it was a browser.
    */
   void setIsApp(in unsigned long ownAppId);

   /**
    * Indicate that this docshell corresponds to a browser inside an app with
    * the given ID.  As with setIsApp, you may pass NO_APP_ID or
    * UNKNOWN_APP_ID.
    *
    * As with setIsApp, you may call this more than once, but it's kind of a
    * hack, so be careful.
    */
   void setIsBrowserInsideApp(in unsigned long containingAppId);

  /**
   * Returns the id of the app associated with this docshell.  If this docshell
   * is an <iframe mozbrowser> inside an <iframe mozapp>, we return the app's
   * appId.
   *
   * We compute this value by walking up the docshell hierarchy until we find a
   * docshell on which setIsApp(x) or setIsBrowserInsideApp(x) was called
   * (ignoring those docshells where x == UNKNOWN_APP_ID).  We return the app
   * id x.
   *
   * If we don't find a docshell with an associated app id in our hierarchy, we
   * return NO_APP_ID.  We never return UNKNOWN_APP_ID.
   *
   * Notice that a docshell may have an associated app even if it returns true
   * for isBrowserElement!
   */
  [infallible] readonly attribute unsigned long appId;

  /**
   * Like nsIDocShellTreeItem::GetSameTypeParent, except this ignores <iframe
   * mozbrowser> and <iframe mozapp> boundaries.
   */
  nsIDocShell getSameTypeParentIgnoreBrowserAndAppBoundaries();

  /** 
   * True iff asynchronous panning and zooming is enabled for this
   * docshell.
   */
  readonly attribute bool asyncPanZoomEnabled;

  /**
   * The sandbox flags on the docshell. These reflect the value of the sandbox
   * attribute of the associated IFRAME or CSP-protectable content, if
   * existent. See the HTML5 spec for more details.
   * These flags on the docshell reflect the current state of the sandbox
   * attribute, which is modifiable. They are only used when loading new
   * content, sandbox flags are also immutably set on the document when it is
   * loaded.
   * The sandbox flags of a document depend on the sandbox flags on its
   * docshell and of its parent document, if any.
   * See nsSandboxFlags.h for the possible flags.
   */
  attribute unsigned long sandboxFlags;

  /**
   * Are plugins allowed in the current document loaded in this docshell ?
   * (if there is one). This depends on whether plugins are allowed by this
   * docshell itself or if the document is sandboxed and hence plugins should
   * not be allowed.
   */
  [noscript, notxpcom] bool pluginsAllowedInCurrentDoc();
  

  /**
   * Attribute that determines whether fullscreen is allowed to be entered for
   * this subtree of the docshell tree. This is true when all iframes containing
   * this docshell have their "allowfullscreen" attribute set to "true".
   * fullscreenAllowed is only writable at content boundaries, where it is used
   * to propagate the value of the cross process parent's iframe's
   * "allowfullscreen" attribute to the child process. Setting
   * fullscreenAllowed on docshells which aren't content boundaries throws an
   * exception.
   */
  [infallible] readonly attribute boolean fullscreenAllowed;
  
  void setFullscreenAllowed(in boolean allowed);
};