path: root/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 "domstubs.idl"
#include "nsIDocShellTreeItem.idl"
#include "nsIRequest.idl"

%{ C++
#include "js/TypeDecls.h"
#include "mozilla/Maybe.h"
#include "mozilla/NotNull.h"
#include "mozilla/UniquePtr.h"
#include "nsCOMPtr.h"
#include "nsIURI.h"
class nsCommandManager;
class nsPresContext;
class nsDocShellLoadState;
namespace mozilla {
class Encoding;
class HTMLEditor;
class PresShell;
namespace dom {
class BrowsingContext;
class ClientSource;
} // namespace dom
}
%}

/**
 * The nsIDocShell interface.
 */

[ptr] native nsPresContext(nsPresContext);
[ptr] native nsCommandManager(nsCommandManager);
[ptr] native PresShell(mozilla::PresShell);
[ref] native MaybeURI(mozilla::Maybe<nsCOMPtr<nsIURI>>);
[ref] native Encoding(const mozilla::Encoding*);
      native UniqueClientSource(mozilla::UniquePtr<mozilla::dom::ClientSource>);

interface nsIURI;
interface nsIChannel;
interface nsIContentSecurityPolicy;
interface nsIDocumentViewer;
interface nsIEditor;
interface nsIEditingSession;
interface nsIInputStream;
interface nsIRequest;
interface nsISHEntry;
interface nsILayoutHistoryState;
interface nsISecureBrowserUI;
interface nsIScriptGlobalObject;
interface nsIStructuredCloneContainer;
interface nsIDOMStorage;
interface nsIPrincipal;
interface nsIPrivacyTransitionObserver;
interface nsIReflowObserver;
interface nsIScrollObserver;
interface nsIRemoteTab;
interface nsIBrowserChild;
interface nsICommandParams;
interface nsILoadURIDelegate;
native BrowserChildRef(already_AddRefed<nsIBrowserChild>);
native nsDocShellLoadStatePtr(nsDocShellLoadState*);

webidl BrowsingContext;
webidl ContentFrameMessageManager;
webidl EventTarget;
webidl Document;

/**
 * nsIDocShell is an interface corresponding to the native nsDocShell object,
 * which is a legacy in-process object roughly corresponding to a 'browsing
 * context', as created for a browser tab or an iframe, for example.
 *
 * nsIDocShell has a 1:1 relationship with its paired dom::BrowsingContext and
 * nsGlobalWindowOuter. It may be replaced during navigation.
 *
 * See also the comment documenting dom::BrowsingContext and the documentation
 * at:
 *
 * https://html.spec.whatwg.org/multipage/document-sequences.html#browsing-context
 * https://firefox-source-docs.mozilla.org/dom/navigation/embedding.html
 * https://firefox-source-docs.mozilla.org/dom/navigation/nav_replace.html
 */
[scriptable, builtinclass, uuid(049234fe-da10-478b-bc5d-bc6f9a1ba63d)]
interface nsIDocShell : nsIDocShellTreeItem
{
  void setCancelContentJSEpoch(in long aEpoch);

  /**
   * 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 aLoadState This is the extended load info for this load.
   * @param aSetNavigating If we should set isNavigating to true while initiating
   *                       the load.
   */
  [noscript]void loadURI(in nsDocShellLoadStatePtr aLoadState, in boolean aSetNavigating);

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

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

  /**
   * Helper for the session store to change the URI associated with the
   * document.
   */
  void setCurrentURIForSessionStore(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 and all dynamic subframe history entries are removed as well.
   *
   * @param isUnload
   *        True to fire the unload event in addition to the pagehide event,
   *        and remove all dynamic subframe history entries.
   */
  [noscript] void firePageHideNotification(in boolean isUnload);

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

  /**
   * Presentation shell for the currently loaded document.  This may be null.
   */
  [notxpcom,nostdcall] readonly attribute PresShell presShell;

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

  /**
   * Document Viewer that is currently loaded for this DocShell.  This may
   * change as the underlying content changes.
   */
  [infallible] readonly attribute nsIDocumentViewer docViewer;

  /**
   * Get the id of the outer window that is or will be in this docshell.
   */
  [infallible] readonly attribute unsigned long long outerWindowID;

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

  /**
   * This allows chrome to set a custom User agent on a specific docshell
   */
  attribute AString customUserAgent;

  /**
   * Whether CSS error reporting is enabled.
   */
  attribute boolean cssErrorReportingEnabled;

  /**
   * 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 stating whether or not media (audio/video) should be loaded.
   */
  [infallible] attribute boolean allowMedia;

  /**
   * 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;

  /**
   * True if the docshell allows its content to be handled by a content listener
   * other than the docshell itself, including the external helper app service,
   * and false otherwise.  Defaults to true.
   */
  [infallible] attribute boolean allowContentRetargeting;

  /**
   * True if new child docshells should allow content retargeting.
   * Setting allowContentRetargeting also overwrites this value.
   */
  [infallible] attribute boolean allowContentRetargetingOnChildren;

  /**
   * Get an array of 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.
   */

  cenum DocShellEnumeratorDirection : 8 {
    ENUMERATE_FORWARDS  = 0,
    ENUMERATE_BACKWARDS = 1
  };

  Array<nsIDocShell> getAllDocShellsInSubtree(in long aItemType,
                                              in nsIDocShell_DocShellEnumeratorDirection aDirection);

  /**
   * The type of application that created this window.
   *
   * DO NOT DELETE, see bug 176166. For firefox, this value will always be
   * UNKNOWN. However, it is used heavily in Thunderbird/comm-central and we
   * don't really have a great replacement at the moment, so we'll just leave it
   * here.
   */
  cenum AppType : 8 {
    APP_TYPE_UNKNOWN = 0,
    APP_TYPE_MAIL    = 1,
    APP_TYPE_EDITOR  = 2
  };

  [infallible] attribute nsIDocShell_AppType appType;

  /**
   * certain docshells (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;

  /*
   * Tells the docshell to offer focus to its tree owner.
   * This is currently only necessary for embedding chrome.
   * If forDocumentNavigation is true, then document navigation should be
   * performed, where only the root of documents are selected. Otherwise, the
   * next element in the parent should be returned. Returns true if focus was
   * successfully taken by the tree owner.
   */
  boolean tabToTreeOwner(in boolean forward, in boolean forDocumentNavigation);

  /**
   * Current busy state for DocShell
   */
  cenum BusyFlags : 8 {
    BUSY_FLAGS_NONE             = 0,
    BUSY_FLAGS_BUSY             = 1,
    BUSY_FLAGS_BEFORE_PAGE_LOAD = 2,
    BUSY_FLAGS_PAGE_LOADING     = 4,
  };

  [infallible] readonly attribute nsIDocShell_BusyFlags busyFlags;

  /**
   * Load commands for the document
   */
  cenum LoadCommand : 8 {
    LOAD_CMD_NORMAL  = 0x1,   // Normal load
    LOAD_CMD_RELOAD  = 0x2,   // Reload
    LOAD_CMD_HISTORY = 0x4,   // Load from history
    LOAD_CMD_PUSHSTATE = 0x8, // History.pushState()
  };

  /*
   * Attribute to access the loadtype for the document. LoadType Enum is
   * defined in nsDocShellLoadTypes.h
   */
  [infallible] attribute unsigned long loadType;

  /*
   * Default load flags (as defined in nsIRequest) that will be set on all
   * requests made by this docShell and propagated to all child docShells and
   * to nsILoadGroup::defaultLoadFlags for the docShell's loadGroup.
   * Default is no flags.  Once set, only future requests initiated by the
   * docShell are affected, so in general, these flags should be set before
   * the docShell loads any content.
   */
  attribute nsLoadFlags defaultLoadFlags;

  /*
   * 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;

  /**
   * Object used to delegate URI loading to an upper context.
   * Currently only set for GeckoView to allow handling of load requests
   * at the application level.
   */
  readonly attribute nsILoadURIDelegate loadURIDelegate;

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

  void clearCachedUserAgent();

  void clearCachedPlatform();

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

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

  /**
   * Display a load error in a frame while keeping that frame's currentURI
   * pointing correctly to the page where the error ocurred, rather than to
   * the error document page. You must provide either the aURI or aURL parameter.
   *
   * @param  aError         The error code to be displayed
   * @param  aURI           nsIURI of the page where the error happened
   * @param  aURL           wstring of the page where the error happened
   * @param  aFailedChannel The channel related to this error
   *
   * Returns whether or not we displayed an error page (note: will always
   * return false if in-content error pages are disabled!)
   */
  boolean displayLoadError(in nsresult aError,
                           in nsIURI aURI,
                           in wstring aURL,
                           [optional] in nsIChannel aFailedChannel);

  /**
   * The channel that failed to load and resulted in an error page.
   * May be null. Relevant only to error pages.
   */
  readonly attribute nsIChannel failedChannel;

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

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

  /**
   * 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;

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

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

  /**
   * Propagated to the print preview document viewer.  Must only be called on
   * a document viewer that has been initialized for print preview.
   */
  void exitPrintPreview();

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

  /**
   * Helper method for accessing this value from C++
   */
  [noscript, notxpcom] nsIDRef HistoryID();

  /**
   * Create a new about:blank document and content viewer.
   * @param aPrincipal the principal to use for the new document.
   * @param aPartitionedPrincipal the partitioned principal to use for the new
   *        document.
   * @param aCsp the CSP to use for the new document.
   */
  void createAboutBlankDocumentViewer(in nsIPrincipal aPrincipal,
                                     in nsIPrincipal aPartitionedPrincipal,
                                     [optional] in nsIContentSecurityPolicy aCSP);

  /**
   * Upon getting, returns the canonical encoding label of the document
   * currently loaded into this docshell.
   */
  readonly attribute ACString charset;

  void forceEncodingDetection();

  /**
   * In a child docshell, this is the charset of the parent docshell
   */
  [noscript, notxpcom, nostdcall] void setParentCharset(
    in Encoding parentCharset,
    in int32_t parentCharsetSource,
    in nsIPrincipal parentCharsetPrincipal);
  [noscript, notxpcom, nostdcall] void getParentCharset(
    out Encoding parentCharset,
    out int32_t parentCharsetSource,
    out nsIPrincipal parentCharsetPrincipal);

  /**
   * Return a DOMHighResTimeStamp representing the number of
   * milliseconds from an arbitrary point in time.  The reference
   * point is shared by all DocShells and is also used by timestamps
   * on markers.
   */
  DOMHighResTimeStamp now();

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

  /**
   * Add an observer to the list of parties to be notified when reflows are
   * occurring. |obs| must support weak references.
   */
  void addWeakReflowObserver(in nsIReflowObserver obs);

  /**
   * Remove an observer from the list of parties to be notified about reflows.
   */
  void removeWeakReflowObserver(in nsIReflowObserver obs);

  /**
   * Notify all attached observers that a reflow has just occurred.
   *
   * @param interruptible if true, the reflow was interruptible.
   * @param start         timestamp when reflow started, in milliseconds since
   *                      navigationStart (accurate to 1/1000 of a ms)
   * @param end           timestamp when reflow ended, in milliseconds since
   *                      navigationStart (accurate to 1/1000 of a ms)
   */
  [noscript] void notifyReflowObservers(in boolean interruptible,
                                        in DOMHighResTimeStamp start,
                                        in DOMHighResTimeStamp end);

  /**
   * Add an observer to the list of parties to be notified when scroll position
   * of some elements is changed.
   */
  [noscript] void addWeakScrollObserver(in nsIScrollObserver obs);

  /**
   * Add an observer to the list of parties to be notified when scroll position
   * of some elements is changed.
   */
  [noscript] void removeWeakScrollObserver(in nsIScrollObserver obs);

  /**
   * Notify all attached observers that the scroll position of some element
   * has changed.
   */
  [noscript] void notifyScrollObservers();

  /**
   * Returns true if this docshell is the top level content docshell.
   */
  [infallible] readonly attribute boolean isTopLevelContentDocShell;

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

  /**
   * Indicates whether the UI may enable the character encoding menu. The UI
   * must disable the menu when this property is false.
   */
  [infallible] readonly attribute boolean mayEnableCharacterEncodingMenu;

           attribute  nsIEditor editor;
  readonly attribute  boolean   editable;             /* this docShell is editable */
  readonly attribute  boolean   hasEditingSession;    /* this docShell has an editing session */

  /**
   * Make this docShell editable, setting a flag that causes
   * an editor to get created, either immediately, or after
   * a url has been loaded.
   *      @param  inWaitForUriLoad    true to wait for a URI before
   *                                  creating the editor.
   */
  void makeEditable(in boolean inWaitForUriLoad);

  /**
   * Returns false for mLSHE, true for mOSHE
   */
  boolean getCurrentSHEntry(out nsISHEntry aEntry);

  /**
    * Cherry picked parts of nsIController.
    * They are here, because we want to call these functions
    * from JS.
    */
  boolean isCommandEnabled(in string command);
  [can_run_script]
  void doCommand(in string command);
  [can_run_script]
  void doCommandWithParams(in string command, in nsICommandParams aParams);

  /**
   * Invisible DocShell are dummy construct to simulate DOM windows
   * without any actual visual representation. They have to be marked
   * at construction time, to avoid any painting activity.
   */
  [noscript, notxpcom] boolean IsInvisible();
  [noscript, notxpcom] void SetInvisible(in boolean aIsInvisibleDocshell);

/**
 * Get the script global for the document in this docshell.
*/
  [noscript,notxpcom,nostdcall] nsIScriptGlobalObject GetScriptGlobalObject();

  [noscript,notxpcom,nostdcall] Document getExtantDocument();

  /**
   * This attribute determines whether a document which is not about:blank has
   * already be loaded by this docShell.
   */
  [infallible] readonly attribute boolean hasLoadedNonBlankURI;

  /**
   * Allow usage of -moz-window-dragging:drag for content docshells.
   * True for top level chrome docshells. Throws if set to false with
   * top level chrome docshell.
   */
  attribute boolean windowDraggingAllowed;

  /**
   * Sets/gets the current scroll restoration mode.
   * @see https://html.spec.whatwg.org/#dom-history-scroll-restoration
   */
  attribute boolean currentScrollRestorationIsManual;

  /**
   * Setter and getter for the origin attributes living on this docshell.
   */
  [implicit_jscontext]
  jsval getOriginAttributes();

  [implicit_jscontext]
  void setOriginAttributes(in jsval aAttrs);

  /**
   * The editing session for this docshell.
   */
  readonly attribute nsIEditingSession editingSession;

  /**
   * The browser child for this docshell.
   */
  [binaryname(ScriptableBrowserChild)] readonly attribute nsIBrowserChild browserChild;
  [noscript,notxpcom,nostdcall] BrowserChildRef GetBrowserChild();

  [noscript,nostdcall,notxpcom] nsCommandManager GetCommandManager();

  /**
   * Attribute that determines whether tracking protection is enabled.
   */
  attribute boolean useTrackingProtection;

 /**
  * Fire a dummy location change event asynchronously.
  */
  [noscript] void dispatchLocationChangeEvent();


  /**
   * Start delayed autoplay media which are in the current document.
   */
  [noscript] void startDelayedAutoplayMediaComponents();

  /**
   * Take ownership of the ClientSource representing an initial about:blank
   * document that was never needed.  As an optimization we avoid creating
   * this document if no code calls GetDocument(), but we still need a
   * ClientSource object to represent the about:blank window.  This may return
   * nullptr; for example if the docshell has created a real window and document
   * already.
   */
  [noscript, nostdcall, notxpcom]
  UniqueClientSource TakeInitialClientSource();

  void setColorMatrix(in Array<float> aMatrix);

  /**
   * Returns true if the current load is a forced reload,
   * e.g. started by holding shift whilst triggering reload.
   */
  readonly attribute boolean isForceReloading;

  Array<float> getColorMatrix();

%{C++
  /**
   * These methods call nsDocShell::GetHTMLEditorInternal() and
   * nsDocShell::SetHTMLEditorInternal() with static_cast.
   */
  mozilla::HTMLEditor* GetHTMLEditor();
  nsresult SetHTMLEditor(mozilla::HTMLEditor* aHTMLEditor);
%}

  /**
   * The message manager for this docshell.  This does not throw, but
   * can return null if the docshell has no message manager.
   */
  [infallible] readonly attribute ContentFrameMessageManager messageManager;

   /**
   * This returns a Promise which resolves to a boolean. True when the
   * document has Tracking Content that has been blocked from loading, false
   * otherwise.
   */
  Promise getHasTrackingContentBlocked();

  /**
   * Return whether this docshell is "attempting to navigate" in the
   * sense that's relevant to document.open.
   */
  [notxpcom, nostdcall] readonly attribute boolean isAttemptingToNavigate;

  /*
   * Whether or not this docshell is executing a nsIWebNavigation navigation
   * method.
   *
   * This will be true when the following methods are executing:
   *   nsIWebNavigation.binaryLoadURI
   *   nsIWebNavigation.goBack
   *   nsIWebNavigation.goForward
   *   nsIWebNavigation.gotoIndex
   *   nsIWebNavigation.loadURI
   */
  [infallible] readonly attribute boolean isNavigating;

  /**
   * @see nsISHEntry synchronizeLayoutHistoryState().
   */
  void synchronizeLayoutHistoryState();

  /**
   * This attempts to save any applicable layout history state (like
   * scroll position) in the nsISHEntry. This is normally done
   * automatically when transitioning from page to page in the
   * same process. We expose this function to support transitioning
   * from page to page across processes as a workaround for bug 1630234
   * until session history state is moved into the parent process.
   */
  void persistLayoutHistoryState();
};