gecko-dev/dom/interfaces/base/nsIBrowser.idl

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

interface nsIContentSecurityPolicy;
interface nsIPrincipal;
interface nsITransportSecurityInfo;
interface nsIURI;
interface nsIWebProgress;
interface nsIReferrerInfo;
interface nsIOpenWindowInfo;

webidl FrameLoader;

[scriptable, uuid(14e5a0cb-e223-4202-95e8-fe53275193ea)]
interface nsIBrowser : nsISupports
{
  /**
   * Gets an optional frame loader that is "related" to this browser.
   * If this exists, then we should attempt to use the same content parent as
   * this frame loader for any new remote tabs.  For example, view source
   * browsers set this to the frame loader for the original content to ensure
   * they are loaded in the same process as the content.
   */
  readonly attribute FrameLoader sameProcessAsFrameLoader;

  /**
   * Gets the optional open window information provided by the window creation
   * code and used to initialize a new browser.
   */
  attribute nsIOpenWindowInfo openWindowInfo;

  /*
   * Called by the child to inform the parent that links are dropped into
   * content area.
   *
   * @param links a flat array of url, name, and type for each link
   * @param triggeringPrincipal a principal that initiated loading
   *                            of the dropped links
   */
  void dropLinks(in Array<AString> links,
                 in nsIPrincipal triggeringPrincipal);

  /**
   * Swapping of frameloaders are usually initiated from a frameloader owner
   * or other components operating on frameloader owners. This is done by calling
   * swapFrameLoaders at MozFrameLoaderOwner webidl interface.
   *
   * This function aimed to provide the other way around -
   * if the swapping is initiated from frameloader itself or other platform level
   * components, it uses this interface to delegate the swapping request to
   * frameloader owners and ask them to re-initiate frameloader swapping, so that
   * frameloader owners such as <xul:browser> can setup their properties and /
   * or listeners properly on swapping.
   */
  void swapBrowsers(in nsIBrowser aOtherBrowser);

  /**
   * Close the browser (usually means to remove a tab).
   */
  void closeBrowser();

  /**
   * A browser can change from remote to non-remote and vice versa.
   * For example, when navigating from an in-process chrome page to
   * a web page, this value would change from false to true.
   */
  readonly attribute boolean isRemoteBrowser;

  /**
   * The nsIWebProgress instance responsible for handling progress events
   * from the content process.
   *
   * Will always be non-null when isRemoteBrowser is true.
   */
  readonly attribute nsIWebProgress remoteWebProgressManager;

  readonly attribute nsIPrincipal contentPrincipal;
  readonly attribute nsIPrincipal contentStoragePrincipal;
  readonly attribute nsIPrincipal contentBlockingAllowListPrincipal;
  readonly attribute nsIContentSecurityPolicy csp;
  readonly attribute nsIReferrerInfo referrerInfo;

  /**
   * Whether or not the browser is in the process of an nsIWebNavigation
   * navigation method.
   */
  attribute boolean isNavigating;

  /**
   * Whether or not the character encoding menu may be enabled.
   */
  attribute boolean mayEnableCharacterEncodingMenu;

  /**
   * Whether or not the character encoding was detected by analyzing
   * content (as opposed to reading a protocol label).
   */
  attribute boolean charsetAutodetected;

  /**
   * Called by Gecko to update the browser when its state changes.
   *
   * @param aCharset the new character set of the document
   * @param aDocumentURI the URI of the current document
   * @param aContentType the content type of the document
   */
  void updateForStateChange(in AString aCharset,
                            in nsIURI aDocumentURI,
                            in AString aContentType);

  /**
   * Called by Gecko to update the nsIWebNavigation when a location change occurs.
   *
   * @param aCanGoBack whether or not the nsIWebNavigation can go backwards in
   *                   history
   * @param aCanGoForward whether or not the nsIWebNavigation can go
   *                      forward in history
   */
  void updateWebNavigationForLocationChange(in boolean aCanGoBack,
                                            in boolean aCanGoForward);

  /**
   * Called by Gecko to update the browser when a location change occurs.
   *
   * @param aLocation the new location
   * @param aCharset the character set of the document
   * @param aMayEnableCharacterEncodingMenu whether or not the content encoding
   *                                        menu may be enabled
   * @param aCharsetAutodetected whether or not the given character set was
   *                             autodetected
   * @param aDocumentURI the URI of the new document
   * @param aTitle the title of the new doucment
   * @param aContentPrincipal the security principal of the new document
   * @param aContentStoragePrincipal the security principal for the new
   *                                 document's storage
   * @param aCSP the content security policy of the new document
   * @param aReferrerInfo the referrer info of the new document
   * @param aIsSynthetic whether or not the document is synthetic
   * @param aInnerWindowID the inner window ID of the document
   * @param aHasRequestContextID whether or not the the request context has a
   *                             value (true) or null should be used (false)
   * @param aRequestContextID the request context ID
   * @param aContentType the content type of the document
   */
  void updateForLocationChange(in nsIURI aLocation,
                               in AString aCharset,
                               in boolean aMayEnableCharacterEncodingMenu,
                               in boolean aCharsetAutodetected,
                               in nsIURI aDocumentURI,
                               in AString aTitle,
                               in nsIPrincipal aContentPrincipal,
                               in nsIPrincipal aContentStoragePrincipal,
                               in nsIContentSecurityPolicy aCSP,
                               in nsIReferrerInfo aReferrerInfo,
                               in boolean aIsSynthetic,
                               in uint64_t aInnerWindowID,
                               in boolean aHasRequestContextID,
                               in uint64_t aRequestContextID,
                               in AString aContentType);

  /**
   * Called by Gecko when it wants to change the process which is currently
   * being used to render content in this tab.
   *
   * Returns a promise which will be resolved with the ChildID of the new
   * process.
   *
   * @param aRemoteType the new remote type to switch this browser into
   * @param aPendingSwitchId unique identifier for the ongoing
   *                         process-switching load
   * @param aReplaceBrowsingContext if true, do not preserve the
   *                                BrowsingContext loaded inside this
   *                                browser after changing processes.
   */
  Promise performProcessSwitch(in AString aRemoteType,
                               in uint64_t aPendingSwitchId,
                               in boolean aReplaceBrowsingContext);

  /** If `true`, this browser supports the `performProcessSwitch` method */
  readonly attribute bool canPerformProcessSwitch;
};