"Fossies" - the Fresh Open Source Software Archive

Member "firefox-69.0.1/docshell/base/nsIWebNavigation.idl" (17 Sep 2019, 11937 Bytes) of package /linux/www/firefox-69.0.1.source.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) IDL source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "nsIWebNavigation.idl": 60.7.2_vs_68.0.

    1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
    2  * This Source Code Form is subject to the terms of the Mozilla Public
    3  * License, v. 2.0. If a copy of the MPL was not distributed with this
    4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
    5 
    6 #include "nsISupports.idl"
    7 
    8 interface nsIInputStream;
    9 interface nsISHistory;
   10 interface nsIURI;
   11 interface nsIPrincipal;
   12 interface nsIChildSHistory;
   13 webidl Document;
   14 
   15 %{ C++
   16 #include "mozilla/dom/ChildSHistory.h"
   17 namespace mozilla {
   18 namespace dom {
   19 struct LoadURIOptions;
   20 } // namespace dom
   21 } // namespace mozilla
   22 %}
   23 
   24 [ref] native LoadURIOptionsRef(const mozilla::dom::LoadURIOptions);
   25 
   26 /**
   27  * The nsIWebNavigation interface defines an interface for navigating the web.
   28  * It provides methods and attributes to direct an object to navigate to a new
   29  * location, stop or restart an in process load, or determine where the object
   30  * has previously gone.
   31  */
   32 [scriptable, uuid(3ade79d4-8cb9-4952-b18d-4f9b63ca0d31)]
   33 interface nsIWebNavigation : nsISupports
   34 {
   35   /**
   36    * Indicates if the object can go back.  If true this indicates that
   37    * there is back session history available for navigation.
   38    */
   39   readonly attribute boolean canGoBack;
   40 
   41   /**
   42    * Indicates if the object can go forward.  If true this indicates that
   43    * there is forward session history available for navigation
   44    */
   45   readonly attribute boolean canGoForward;
   46 
   47   /**
   48    * Tells the object to navigate to the previous session history item.  When a
   49    * page is loaded from session history, all content is loaded from the cache
   50    * (if available) and page state (such as form values and scroll position) is
   51    * restored.
   52    *
   53    * @throw NS_ERROR_UNEXPECTED
   54    *        Indicates that the call was unexpected at this time, which implies
   55    *        that canGoBack is false.
   56    */
   57   void goBack();
   58 
   59   /**
   60    * Tells the object to navigate to the next session history item.  When a
   61    * page is loaded from session history, all content is loaded from the cache
   62    * (if available) and page state (such as form values and scroll position) is
   63    * restored.
   64    *
   65    * @throw NS_ERROR_UNEXPECTED
   66    *        Indicates that the call was unexpected at this time, which implies
   67    *        that canGoForward is false.
   68    */
   69   void goForward();
   70 
   71   /**
   72    * Tells the object to navigate to the session history item at a given index.
   73    *
   74    * @throw NS_ERROR_UNEXPECTED
   75    *        Indicates that the call was unexpected at this time, which implies
   76    *        that session history entry at the given index does not exist.
   77    */
   78   void gotoIndex(in long index);
   79 
   80   /****************************************************************************
   81    * The following flags may be bitwise combined to form the load flags
   82    * parameter passed to either the loadURI or reload method.  Some of these
   83    * flags are only applicable to loadURI.
   84    */
   85 
   86   /**
   87    * This flags defines the range of bits that may be specified.  Flags
   88    * outside this range may be used, but may not be passed to Reload().
   89    */
   90   const unsigned long LOAD_FLAGS_MASK            = 0xffff;
   91 
   92   /**
   93    * This is the default value for the load flags parameter.
   94    */
   95   const unsigned long LOAD_FLAGS_NONE            = 0x0000;
   96 
   97   /**
   98    * Flags 0x1, 0x2, 0x4, 0x8 are reserved for internal use by
   99    * nsIWebNavigation implementations for now.
  100    */
  101 
  102   /**
  103    * This flag specifies that the load should have the semantics of an HTML
  104    * Meta-refresh tag (i.e., that the cache should be bypassed).  This flag
  105    * is only applicable to loadURI.
  106    * XXX the meaning of this flag is poorly defined.
  107    * XXX no one uses this, so we should probably deprecate and remove it.
  108    */
  109   const unsigned long LOAD_FLAGS_IS_REFRESH      = 0x0010;
  110 
  111   /**
  112    * This flag specifies that the load should have the semantics of a link
  113    * click.  This flag is only applicable to loadURI.
  114    * XXX the meaning of this flag is poorly defined.
  115    */
  116   const unsigned long LOAD_FLAGS_IS_LINK         = 0x0020;
  117 
  118   /**
  119    * This flag specifies that history should not be updated.  This flag is only
  120    * applicable to loadURI.
  121    */
  122   const unsigned long LOAD_FLAGS_BYPASS_HISTORY  = 0x0040;
  123 
  124   /**
  125    * This flag specifies that any existing history entry should be replaced.
  126    * This flag is only applicable to loadURI.
  127    */
  128   const unsigned long LOAD_FLAGS_REPLACE_HISTORY = 0x0080;
  129 
  130   /**
  131    * This flag specifies that the local web cache should be bypassed, but an
  132    * intermediate proxy cache could still be used to satisfy the load.
  133    */
  134   const unsigned long LOAD_FLAGS_BYPASS_CACHE    = 0x0100;
  135 
  136   /**
  137    * This flag specifies that any intermediate proxy caches should be bypassed
  138    * (i.e., that the content should be loaded from the origin server).
  139    */
  140   const unsigned long LOAD_FLAGS_BYPASS_PROXY    = 0x0200;
  141 
  142   /**
  143    * This flag specifies that a reload was triggered as a result of detecting
  144    * an incorrect character encoding while parsing a previously loaded
  145    * document.
  146    */
  147   const unsigned long LOAD_FLAGS_CHARSET_CHANGE  = 0x0400;
  148 
  149   /**
  150    * If this flag is set, Stop() will be called before the load starts
  151    * and will stop both content and network activity (the default is to
  152    * only stop network activity).  Effectively, this passes the
  153    * STOP_CONTENT flag to Stop(), in addition to the STOP_NETWORK flag.
  154    */
  155   const unsigned long LOAD_FLAGS_STOP_CONTENT    = 0x0800;
  156 
  157   /**
  158    * A hint this load was prompted by an external program: take care!
  159    */
  160   const unsigned long LOAD_FLAGS_FROM_EXTERNAL   = 0x1000;
  161 
  162   /**
  163     This flag is set when a user explicitly disables the Mixed Content
  164     Blocker, and allows Mixed Content to load on an https page.
  165   */
  166   const unsigned long LOAD_FLAGS_ALLOW_MIXED_CONTENT = 0x2000;
  167 
  168   /**
  169    * This flag specifies that this is the first load in this object.
  170    * Set with care, since setting incorrectly can cause us to assume that
  171    * nothing was actually loaded in this object if the load ends up being
  172    * handled by an external application.  This flag must not be passed to
  173    * Reload.
  174    */
  175   const unsigned long LOAD_FLAGS_FIRST_LOAD = 0x4000;
  176 
  177   /**
  178    * This flag specifies that the load should not be subject to popup
  179    * blocking checks.  This flag must not be passed to Reload.
  180    */
  181   const unsigned long LOAD_FLAGS_ALLOW_POPUPS = 0x8000;
  182 
  183   /**
  184    * This flag specifies that the URI classifier should not be checked for
  185    * this load.  This flag must not be passed to Reload.
  186    */
  187   const unsigned long LOAD_FLAGS_BYPASS_CLASSIFIER = 0x10000;
  188 
  189   /**
  190    * Force relevant cookies to be sent with this load even if normally they
  191    * wouldn't be.
  192    */
  193   const unsigned long LOAD_FLAGS_FORCE_ALLOW_COOKIES = 0x20000;
  194 
  195   /**
  196    * Prevent the owner principal from being inherited for this load.
  197    */
  198   const unsigned long LOAD_FLAGS_DISALLOW_INHERIT_PRINCIPAL = 0x40000;
  199 
  200   /**
  201    * Overwrite the returned error code with a specific result code
  202    * when an error page is displayed.
  203    */
  204   const unsigned long LOAD_FLAGS_ERROR_LOAD_CHANGES_RV = 0x80000;
  205 
  206   /**
  207    * This flag specifies that the URI may be submitted to a third-party
  208    * server for correction. This should only be applied to non-sensitive
  209    * URIs entered by users.  This flag must not be passed to Reload.
  210    */
  211   const unsigned long LOAD_FLAGS_ALLOW_THIRD_PARTY_FIXUP = 0x100000;
  212 
  213   /**
  214    * This flag specifies that common scheme typos should be corrected.
  215    */
  216   const unsigned long LOAD_FLAGS_FIXUP_SCHEME_TYPOS = 0x200000;
  217 
  218   /**
  219    * Allows a top-level data: navigation to occur. E.g. view-image
  220    * is an explicit user action which should be allowed.
  221    */
  222   const unsigned long LOAD_FLAGS_FORCE_ALLOW_DATA_URI = 0x400000;
  223 
  224   /**
  225    * This load is the result of an HTTP redirect.
  226    */
  227   const unsigned long LOAD_FLAGS_IS_REDIRECT = 0x800000;
  228 
  229   /**
  230    * Loads a given URI.  This will give priority to loading the requested URI
  231    * in the object implementing this interface.  If it can't be loaded here
  232    * however, the URI dispatcher will go through its normal process of content
  233    * loading.
  234    *
  235    * @param aURI
  236    *        The URI string to load.  For HTTP and FTP URLs and possibly others,
  237    *        characters above U+007F will be converted to UTF-8 and then URL-
  238    *        escaped per the rules of RFC 2396.
  239    * @param aLoadURIOptions
  240    *        A JSObject defined in LoadURIOptions.webidl holding info like e.g.
  241    *        the triggeringPrincipal, the referrer info.
  242    */
  243   [implicit_jscontext, binaryname(LoadURIFromScript)]
  244   void loadURI(in AString aURI,
  245                in jsval   aLoadURIOptions);
  246 
  247   /**
  248    * A C++ friendly version of loadURI
  249    */
  250   [nostdcall, binaryname(LoadURI)]
  251   void binaryLoadURI(in AString           aURI,
  252                      in LoadURIOptionsRef aLoadURIOptions);
  253 
  254   /**
  255    * Tells the Object to reload the current page.  There may be cases where the
  256    * user will be asked to confirm the reload (for example, when it is
  257    * determined that the request is non-idempotent).
  258    *
  259    * @param aReloadFlags
  260    *        Flags modifying load behaviour.  This parameter is a bitwise
  261    *        combination of the Load Flags defined above.  (Undefined bits are
  262    *        reserved for future use.)  Generally you will pass LOAD_FLAGS_NONE
  263    *        for this parameter.
  264    *
  265    * @throw NS_BINDING_ABORTED
  266    *        Indicating that the user canceled the reload.
  267    */
  268   void reload(in unsigned long aReloadFlags);
  269 
  270   /****************************************************************************
  271    * The following flags may be passed as the stop flags parameter to the stop
  272    * method defined on this interface.
  273    */
  274 
  275   /**
  276    * This flag specifies that all network activity should be stopped.  This
  277    * includes both active network loads and pending META-refreshes.
  278    */
  279   const unsigned long STOP_NETWORK = 0x01;
  280 
  281   /**
  282    * This flag specifies that all content activity should be stopped.  This
  283    * includes animated images, plugins and pending Javascript timeouts.
  284    */
  285   const unsigned long STOP_CONTENT = 0x02;
  286 
  287   /**
  288    * This flag specifies that all activity should be stopped.
  289    */
  290   const unsigned long STOP_ALL     = 0x03;
  291 
  292   /**
  293    * Stops a load of a URI.
  294    *
  295    * @param aStopFlags
  296    *        This parameter is one of the stop flags defined above.
  297    */
  298   void stop(in unsigned long aStopFlags);
  299 
  300   /**
  301    * Retrieves the current DOM document for the frame, or lazily creates a
  302    * blank document if there is none.  This attribute never returns null except
  303    * for unexpected error situations.
  304    */
  305   readonly attribute Document document;
  306 
  307   /**
  308    * The currently loaded URI or null.
  309    */
  310   readonly attribute nsIURI currentURI;
  311 
  312   /**
  313    * The session history object used by this web navigation instance. This
  314    * object will be a mozilla::dom::ChildSHistory object, but is returned as
  315    * nsISupports so it can be called from JS code.
  316    */
  317   [binaryname(SessionHistoryXPCOM)]
  318   readonly attribute nsISupports sessionHistory;
  319 
  320   %{ C++
  321   /**
  322    * Get the session history object used by this nsIWebNavigation instance.
  323    * Use this method instead of the XPCOM method when getting the
  324    * SessionHistory from C++ code.
  325    */
  326   already_AddRefed<mozilla::dom::ChildSHistory>
  327   GetSessionHistory()
  328   {
  329     nsCOMPtr<nsISupports> history;
  330     GetSessionHistoryXPCOM(getter_AddRefs(history));
  331     return history.forget()
  332       .downcast<mozilla::dom::ChildSHistory>();
  333   }
  334   %}
  335 
  336   /**
  337    * Set an OriginAttributes dictionary in the docShell. This can be done only
  338    * before loading any content.
  339    */
  340   [implicit_jscontext]
  341   void setOriginAttributesBeforeLoading(in jsval originAttributes);
  342 
  343   /**
  344    * Resume a load which has been redirected from another process.
  345    *
  346    * A negative |aHistoryIndex| value corresponds to a non-history load being
  347    * resumed.
  348    */
  349   void resumeRedirectedLoad(in unsigned long long aLoadIdentifier,
  350                             in long aHistoryIndex);
  351 };