docshell/base/nsIWebNavigation.idl

   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 URI, the referrer policy.
 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 referring URI for the currently loaded URI or null.
 314    */
 315   readonly attribute nsIURI referringURI;
 316
 317   /**
 318    * The session history object used by this web navigation instance. This
 319    * object will be a mozilla::dom::ChildSHistory object, but is returned as
 320    * nsISupports so it can be called from JS code.
 321    */
 322   [binaryname(SessionHistoryXPCOM)]
 323   readonly attribute nsISupports sessionHistory;
 324
 325   %{ C++
 326   /**
 327    * Get the session history object used by this nsIWebNavigation instance.
 328    * Use this method instead of the XPCOM method when getting the
 329    * SessionHistory from C++ code.
 330    */
 331   already_AddRefed<mozilla::dom::ChildSHistory>
 332   GetSessionHistory()
 333   {
 334     nsCOMPtr<nsISupports> history;
 335     GetSessionHistoryXPCOM(getter_AddRefs(history));
 336     return history.forget()
 337       .downcast<mozilla::dom::ChildSHistory>();
 338   }
 339   %}
 340
 341   /**
 342    * Set an OriginAttributes dictionary in the docShell. This can be done only
 343    * before loading any content.
 344    */
 345   [implicit_jscontext]
 346   void setOriginAttributesBeforeLoading(in jsval originAttributes);
 347
 348   /**
 349    * Resume a load which has been redirected from another process.
 350    */
 351   void resumeRedirectedLoad(in unsigned long long aLoadIdentifier);
 352 };