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  * Even though this is builtinclass, most of the interface is also implemented
  33  * in RemoteWebNavigation, so if this interface changes, the implementation
  34  * there may also need to change.
  35  */
  36 [scriptable, builtinclass, uuid(3ade79d4-8cb9-4952-b18d-4f9b63ca0d31)]
  37 interface nsIWebNavigation : nsISupports
  38 {
  39   /**
  40    * Indicates if the object can go back.  If true this indicates that
  41    * there is back session history available for navigation.
  42    */
  43   readonly attribute boolean canGoBack;
  44
  45   /**
  46    * Indicates if the object can go forward.  If true this indicates that
  47    * there is forward session history available for navigation
  48    */
  49   readonly attribute boolean canGoForward;
  50
  51   /**
  52    * Tells the object to navigate to the previous session history item.  When a
  53    * page is loaded from session history, all content is loaded from the cache
  54    * (if available) and page state (such as form values and scroll position) is
  55    * restored.
  56    *
  57    * @param {boolean} aRequireUserInteraction
  58    *        Tells goBack to skip history items that did not record any user
  59    *        interaction on their corresponding document while they were active.
  60    *        This means in case of multiple entries mapping to the same document,
  61    *        each entry has to have been flagged with user interaction separately.
  62    *        If no items have user interaction, the function will fall back
  63    *        to the first session history entry.
  64    *
  65    * @param {boolean} aUserActivation
  66    *        Tells goBack that the call was triggered by a user action (e.g.:
  67    *        The user clicked the back button).
  68    *
  69    * @throw NS_ERROR_UNEXPECTED
  70    *        Indicates that the call was unexpected at this time, which implies
  71    *        that canGoBack is false.
  72    */
  73   void goBack([optional] in boolean aRequireUserInteraction, [optional] in boolean aUserActivation);
  74
  75   /**
  76    * Tells the object to navigate to the next session history item.  When a
  77    * page is loaded from session history, all content is loaded from the cache
  78    * (if available) and page state (such as form values and scroll position) is
  79    * restored.
  80    *
  81    * @param {boolean} aRequireUserInteraction
  82    *        Tells goForward to skip history items that did not record any user
  83    *        interaction on their corresponding document while they were active.
  84    *        This means in case of multiple entries mapping to the same document,
  85    *        each entry has to have been flagged with user interaction separately.
  86    *        If no items have user interaction, the function will fall back
  87    *        to the latest session history entry.
  88    *
  89    * @param {boolean} aUserActivation
  90    *        Tells goForward that the call was triggered by a user action (e.g.:
  91    *        The user clicked the forward button).
  92    *
  93    * @throw NS_ERROR_UNEXPECTED
  94    *        Indicates that the call was unexpected at this time, which implies
  95    *        that canGoForward is false.
  96    */
  97   void goForward([optional] in boolean aRequireUserInteraction, [optional] in boolean aUserActivation);
  98
  99   /**
 100    * Tells the object to navigate to the session history item at a given index.
 101    *
 102    * @param {boolean} aUserActivation
 103    *        Tells goForward that the call was triggered by a user action (e.g.:
 104    *        The user clicked the forward button).
 105    *
 106    * @throw NS_ERROR_UNEXPECTED
 107    *        Indicates that the call was unexpected at this time, which implies
 108    *        that session history entry at the given index does not exist.
 109    */
 110   void gotoIndex(in long index, [optional] in boolean aUserActivation);
 111
 112   /****************************************************************************
 113    * The following flags may be bitwise combined to form the load flags
 114    * parameter passed to either the loadURI or reload method.  Some of these
 115    * flags are only applicable to loadURI.
 116    */
 117
 118   /**
 119    * This flags defines the range of bits that may be specified.  Flags
 120    * outside this range may be used, but may not be passed to Reload().
 121    */
 122   const unsigned long LOAD_FLAGS_MASK            = 0xffff;
 123
 124   /**
 125    * This is the default value for the load flags parameter.
 126    */
 127   const unsigned long LOAD_FLAGS_NONE            = 0x0000;
 128
 129   /**
 130    * Flags 0x1, 0x2, 0x4, 0x8 are reserved for internal use by
 131    * nsIWebNavigation implementations for now.
 132    */
 133
 134   /**
 135    * This flag specifies that the load should have the semantics of an HTML
 136    * Meta-refresh tag (i.e., that the cache should be bypassed).  This flag
 137    * is only applicable to loadURI.
 138    * XXX the meaning of this flag is poorly defined.
 139    * XXX no one uses this, so we should probably deprecate and remove it.
 140    */
 141   const unsigned long LOAD_FLAGS_IS_REFRESH      = 0x0010;
 142
 143   /**
 144    * This flag specifies that the load should have the semantics of a link
 145    * click.  This flag is only applicable to loadURI.
 146    * XXX the meaning of this flag is poorly defined.
 147    */
 148   const unsigned long LOAD_FLAGS_IS_LINK         = 0x0020;
 149
 150   /**
 151    * This flag specifies that history should not be updated.  This flag is only
 152    * applicable to loadURI.
 153    */
 154   const unsigned long LOAD_FLAGS_BYPASS_HISTORY  = 0x0040;
 155
 156   /**
 157    * This flag specifies that any existing history entry should be replaced.
 158    * This flag is only applicable to loadURI.
 159    */
 160   const unsigned long LOAD_FLAGS_REPLACE_HISTORY = 0x0080;
 161
 162   /**
 163    * This flag specifies that the local web cache should be bypassed, but an
 164    * intermediate proxy cache could still be used to satisfy the load.
 165    */
 166   const unsigned long LOAD_FLAGS_BYPASS_CACHE    = 0x0100;
 167
 168   /**
 169    * This flag specifies that any intermediate proxy caches should be bypassed
 170    * (i.e., that the content should be loaded from the origin server).
 171    */
 172   const unsigned long LOAD_FLAGS_BYPASS_PROXY    = 0x0200;
 173
 174   /**
 175    * This flag specifies that a reload was triggered as a result of detecting
 176    * an incorrect character encoding while parsing a previously loaded
 177    * document.
 178    */
 179   const unsigned long LOAD_FLAGS_CHARSET_CHANGE  = 0x0400;
 180
 181   /**
 182    * If this flag is set, Stop() will be called before the load starts
 183    * and will stop both content and network activity (the default is to
 184    * only stop network activity).  Effectively, this passes the
 185    * STOP_CONTENT flag to Stop(), in addition to the STOP_NETWORK flag.
 186    */
 187   const unsigned long LOAD_FLAGS_STOP_CONTENT    = 0x0800;
 188
 189   /**
 190    * A hint this load was prompted by an external program: take care!
 191    */
 192   const unsigned long LOAD_FLAGS_FROM_EXTERNAL   = 0x1000;
 193
 194   /**
 195    * This flag specifies that this is the first load in this object.
 196    * Set with care, since setting incorrectly can cause us to assume that
 197    * nothing was actually loaded in this object if the load ends up being
 198    * handled by an external application.  This flag must not be passed to
 199    * Reload.
 200    */
 201   const unsigned long LOAD_FLAGS_FIRST_LOAD = 0x4000;
 202
 203   /**
 204    * This flag specifies that the load should not be subject to popup
 205    * blocking checks.  This flag must not be passed to Reload.
 206    */
 207   const unsigned long LOAD_FLAGS_ALLOW_POPUPS = 0x8000;
 208
 209   /**
 210    * This flag specifies that the URI classifier should not be checked for
 211    * this load.  This flag must not be passed to Reload.
 212    */
 213   const unsigned long LOAD_FLAGS_BYPASS_CLASSIFIER = 0x10000;
 214
 215   /**
 216    * Force relevant cookies to be sent with this load even if normally they
 217    * wouldn't be.
 218    */
 219   const unsigned long LOAD_FLAGS_FORCE_ALLOW_COOKIES = 0x20000;
 220
 221   /**
 222    * Prevent the owner principal from being inherited for this load.
 223    */
 224   const unsigned long LOAD_FLAGS_DISALLOW_INHERIT_PRINCIPAL = 0x40000;
 225
 226   /**
 227    * Overwrite the returned error code with a specific result code
 228    * when an error page is displayed.
 229    */
 230   const unsigned long LOAD_FLAGS_ERROR_LOAD_CHANGES_RV = 0x80000;
 231
 232   /**
 233    * This flag specifies that the URI may be submitted to a third-party
 234    * server for correction. This should only be applied to non-sensitive
 235    * URIs entered by users.  This flag must not be passed to Reload.
 236    */
 237   const unsigned long LOAD_FLAGS_ALLOW_THIRD_PARTY_FIXUP = 0x100000;
 238
 239   /**
 240    * This flag specifies that common scheme typos should be corrected.
 241    */
 242   const unsigned long LOAD_FLAGS_FIXUP_SCHEME_TYPOS = 0x200000;
 243
 244   /**
 245    * Allows a top-level data: navigation to occur. E.g. view-image
 246    * is an explicit user action which should be allowed.
 247    */
 248   const unsigned long LOAD_FLAGS_FORCE_ALLOW_DATA_URI = 0x400000;
 249
 250   /**
 251    * This load is the result of an HTTP redirect.
 252    */
 253   const unsigned long LOAD_FLAGS_IS_REDIRECT = 0x800000;
 254
 255   /**
 256    * These flags force TRR modes 1 or 3 for the load.
 257    */
 258   const unsigned long LOAD_FLAGS_DISABLE_TRR = 0x1000000;
 259   const unsigned long LOAD_FLAGS_FORCE_TRR = 0x2000000;
 260
 261   /**
 262    * This load should bypass the LoadURIDelegate.loadUri.
 263    */
 264   const unsigned long LOAD_FLAGS_BYPASS_LOAD_URI_DELEGATE = 0x4000000;
 265
 266   /**
 267    * This load has a user activation. (e.g: reload button was clicked)
 268    */
 269   const unsigned long LOAD_FLAGS_USER_ACTIVATION = 0x8000000;
 270
 271   /**
 272    * Loads a given URI.  This will give priority to loading the requested URI
 273    * in the object implementing this interface.  If it can't be loaded here
 274    * however, the URI dispatcher will go through its normal process of content
 275    * loading.
 276    *
 277    * @param aURI
 278    *        The URI to load.
 279    * @param aLoadURIOptions
 280    *        A JSObject defined in LoadURIOptions.webidl holding info like e.g.
 281    *        the triggeringPrincipal, the referrer info.
 282    */
 283   [implicit_jscontext, binaryname(LoadURIFromScript)]
 284   void loadURI(in nsIURI aURI,
 285                in jsval  aLoadURIOptions);
 286
 287   /**
 288    * Parse / fix up a URI out of the string and load it.
 289    * This will give priority to loading the requested URI
 290    * in the object implementing this interface.  If it can't be loaded here
 291    * however, the URI dispatcher will go through its normal process of content
 292    * loading.
 293    *
 294    * @param aURIString
 295    *        The URI string to load.  For HTTP and FTP URLs and possibly others,
 296    *        characters above U+007F will be converted to UTF-8 and then URL-
 297    *        escaped per the rules of RFC 2396.
 298    *        This method may use nsIURIFixup to try to fix up typos etc. in the
 299    *        input string based on the load flag arguments in aLoadURIOptions.
 300    *        It can even convert the input to a search results page using the
 301    *        default search service.
 302    *        If you have an nsIURI anyway, prefer calling `loadURI`, above.
 303    * @param aLoadURIOptions
 304    *        A JSObject defined in LoadURIOptions.webidl holding info like e.g.
 305    *        the triggeringPrincipal, the referrer info.
 306    */
 307   [implicit_jscontext, binaryname(FixupAndLoadURIStringFromScript)]
 308   void fixupAndLoadURIString(in AString aURIString,
 309                              in jsval   aLoadURIOptions);
 310
 311   /**
 312    * A C++ friendly version of loadURI
 313    */
 314   [nostdcall, binaryname(LoadURI)]
 315   void binaryLoadURI(in nsIURI            aURI,
 316                      in LoadURIOptionsRef aLoadURIOptions);
 317
 318   /**
 319    * A C++ friendly version of fixupAndLoadURIString
 320    */
 321   [nostdcall, binaryname(FixupAndLoadURIString)]
 322   void binaryFixupAndLoadURIString(in AString           aURIString,
 323                                    in LoadURIOptionsRef aLoadURIOptions);
 324
 325   /**
 326    * Tells the Object to reload the current page.  There may be cases where the
 327    * user will be asked to confirm the reload (for example, when it is
 328    * determined that the request is non-idempotent).
 329    *
 330    * @param aReloadFlags
 331    *        Flags modifying load behaviour.  This parameter is a bitwise
 332    *        combination of the Load Flags defined above.  (Undefined bits are
 333    *        reserved for future use.)  Generally you will pass LOAD_FLAGS_NONE
 334    *        for this parameter.
 335    *
 336    * @throw NS_BINDING_ABORTED
 337    *        Indicating that the user canceled the reload.
 338    */
 339   void reload(in unsigned long aReloadFlags);
 340
 341   /****************************************************************************
 342    * The following flags may be passed as the stop flags parameter to the stop
 343    * method defined on this interface.
 344    */
 345
 346   /**
 347    * This flag specifies that all network activity should be stopped.  This
 348    * includes both active network loads and pending META-refreshes.
 349    */
 350   const unsigned long STOP_NETWORK = 0x01;
 351
 352   /**
 353    * This flag specifies that all content activity should be stopped.  This
 354    * includes animated images, plugins and pending Javascript timeouts.
 355    */
 356   const unsigned long STOP_CONTENT = 0x02;
 357
 358   /**
 359    * This flag specifies that all activity should be stopped.
 360    */
 361   const unsigned long STOP_ALL     = 0x03;
 362
 363   /**
 364    * Stops a load of a URI.
 365    *
 366    * @param aStopFlags
 367    *        This parameter is one of the stop flags defined above.
 368    */
 369   void stop(in unsigned long aStopFlags);
 370
 371   /**
 372    * Retrieves the current DOM document for the frame, or lazily creates a
 373    * blank document if there is none.  This attribute never returns null except
 374    * for unexpected error situations.
 375    */
 376   readonly attribute Document document;
 377
 378   /**
 379    * The currently loaded URI or null.
 380    */
 381   readonly attribute nsIURI currentURI;
 382
 383   /**
 384    * The session history object used by this web navigation instance. This
 385    * object will be a mozilla::dom::ChildSHistory object, but is returned as
 386    * nsISupports so it can be called from JS code.
 387    */
 388   [binaryname(SessionHistoryXPCOM)]
 389   readonly attribute nsISupports sessionHistory;
 390
 391   %{ C++
 392   /**
 393    * Get the session history object used by this nsIWebNavigation instance.
 394    * Use this method instead of the XPCOM method when getting the
 395    * SessionHistory from C++ code.
 396    */
 397   already_AddRefed<mozilla::dom::ChildSHistory>
 398   GetSessionHistory()
 399   {
 400     nsCOMPtr<nsISupports> history;
 401     GetSessionHistoryXPCOM(getter_AddRefs(history));
 402     return history.forget()
 403       .downcast<mozilla::dom::ChildSHistory>();
 404   }
 405   %}
 406
 407   /**
 408    * Resume a load which has been redirected from another process.
 409    *
 410    * A negative |aHistoryIndex| value corresponds to a non-history load being
 411    * resumed.
 412    */
 413   void resumeRedirectedLoad(in unsigned long long aLoadIdentifier,
 414                             in long aHistoryIndex);
 415 };