gecko/docshell/base/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(9b283337-097d-4fa8-a2da-916318eaf828)]
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 PRUint32 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 PRInt32 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);

  /**
   * Mark the docshell as a browser frame.
   * This should be used for <iframe mozbrowser> but not for <iframe mozapp>.
   *
   * This method should not be called more than once.
   */
  void setIsBrowserElement();

  /**
   * Returns true iff the docshell is marked as a browser frame.
   */
  readonly attribute boolean isBrowserElement;

  /**
   * Returns true iif the docshell is marked as an app frame.
   */
  readonly attribute boolean isApp;

  /**
   * Returns true iif the docshell is marked as a type that behaves like a
   * content boundary.
   */
  readonly attribute boolean isContentBoundary;

  /**
   * Returns true iif the docshell is inside a browser element.
   */
  readonly attribute boolean isInBrowserElement;

  /**
   * Returns true iif the docshell is inside an application.  However, it will
   * return false if the docshell is inside a browser element that is inside
   * an application.
   *
   * Note: Do not use this method for permissions checks!  An app may contain
   * an <iframe> pointing at arbitrary web code.  This iframe's docshell will
   * have isInApp() == true, but the iframe's content is not "app code", and
   * so should not be granted more trust than vanilla web content.
   *
   * (For example, suppose when web content calls API method X, we show a
   * permission prompt, but when "app code" calls method X, we don't.  In this
   * case, it would be /incorrect/ to show the permission prompt if
   * !isInApp().)
   *
   * If you're doing a security check, use the content's principal instead of
   * this method.
   */
  readonly attribute boolean isInApp;

  /**
   * Returns if the docshell has a docshell that behaves as a content boundary
   * in his parent hierarchy.
   */
  readonly attribute boolean isBelowContentBoundary;

  /**
   * Set the app id this docshell is associated with. The id has to be a valid
   * app id. If the docshell isn't associated with any app, the value should be
   * nsIScriptSecurityManager::NO_APP_ID. However, this is the default value if
   * nothing is et.
   *
   * This method is [noscript] to reduce the scope. It should be used at very
   * specific moments.
   *
   * Calling setAppId() will mark the frame as an app frame.
   */
  [noscript] void setAppId(in unsigned long appId);

  /**
   * Returns the app id of the app the docshell is in. Returns
   * nsIScriptSecurityManager::NO_APP_ID if the docshell is not in an app.
   */
  readonly attribute unsigned long appId;

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

  /**
   * Like GetSameTypeParent, except this ignores <iframe mozbrowser>
   * boundaries.
   */
  nsIDocShell getParentIgnoreBrowserFrame();

  /**
   * 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();
};