1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docshell/base/nsIWebNavigation.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,353 @@
1.4 +/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.5 + * This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIDOMDocument;
1.12 +interface nsIInputStream;
1.13 +interface nsISHistory;
1.14 +interface nsIURI;
1.15 +
1.16 +/**
1.17 + * The nsIWebNavigation interface defines an interface for navigating the web.
1.18 + * It provides methods and attributes to direct an object to navigate to a new
1.19 + * location, stop or restart an in process load, or determine where the object
1.20 + * has previously gone.
1.21 + */
1.22 +[scriptable, uuid(b7568a50-4c50-442c-a6be-3a340a48d89a)]
1.23 +interface nsIWebNavigation : nsISupports
1.24 +{
1.25 + /**
1.26 + * Indicates if the object can go back. If true this indicates that
1.27 + * there is back session history available for navigation.
1.28 + */
1.29 + readonly attribute boolean canGoBack;
1.30 +
1.31 + /**
1.32 + * Indicates if the object can go forward. If true this indicates that
1.33 + * there is forward session history available for navigation
1.34 + */
1.35 + readonly attribute boolean canGoForward;
1.36 +
1.37 + /**
1.38 + * Tells the object to navigate to the previous session history item. When a
1.39 + * page is loaded from session history, all content is loaded from the cache
1.40 + * (if available) and page state (such as form values and scroll position) is
1.41 + * restored.
1.42 + *
1.43 + * @throw NS_ERROR_UNEXPECTED
1.44 + * Indicates that the call was unexpected at this time, which implies
1.45 + * that canGoBack is false.
1.46 + */
1.47 + void goBack();
1.48 +
1.49 + /**
1.50 + * Tells the object to navigate to the next session history item. When a
1.51 + * page is loaded from session history, all content is loaded from the cache
1.52 + * (if available) and page state (such as form values and scroll position) is
1.53 + * restored.
1.54 + *
1.55 + * @throw NS_ERROR_UNEXPECTED
1.56 + * Indicates that the call was unexpected at this time, which implies
1.57 + * that canGoForward is false.
1.58 + */
1.59 + void goForward();
1.60 +
1.61 + /**
1.62 + * Tells the object to navigate to the session history item at a given index.
1.63 + *
1.64 + * @throw NS_ERROR_UNEXPECTED
1.65 + * Indicates that the call was unexpected at this time, which implies
1.66 + * that session history entry at the given index does not exist.
1.67 + */
1.68 + void gotoIndex(in long index);
1.69 +
1.70 + /****************************************************************************
1.71 + * The following flags may be bitwise combined to form the load flags
1.72 + * parameter passed to either the loadURI or reload method. Some of these
1.73 + * flags are only applicable to loadURI.
1.74 + */
1.75 +
1.76 + /**
1.77 + * This flags defines the range of bits that may be specified. Flags
1.78 + * outside this range may be used, but may not be passed to Reload().
1.79 + */
1.80 + const unsigned long LOAD_FLAGS_MASK = 0xffff;
1.81 +
1.82 + /**
1.83 + * This is the default value for the load flags parameter.
1.84 + */
1.85 + const unsigned long LOAD_FLAGS_NONE = 0x0000;
1.86 +
1.87 + /**
1.88 + * Flags 0x1, 0x2, 0x4, 0x8 are reserved for internal use by
1.89 + * nsIWebNavigation implementations for now.
1.90 + */
1.91 +
1.92 + /**
1.93 + * This flag specifies that the load should have the semantics of an HTML
1.94 + * Meta-refresh tag (i.e., that the cache should be bypassed). This flag
1.95 + * is only applicable to loadURI.
1.96 + * XXX the meaning of this flag is poorly defined.
1.97 + * XXX no one uses this, so we should probably deprecate and remove it.
1.98 + */
1.99 + const unsigned long LOAD_FLAGS_IS_REFRESH = 0x0010;
1.100 +
1.101 + /**
1.102 + * This flag specifies that the load should have the semantics of a link
1.103 + * click. This flag is only applicable to loadURI.
1.104 + * XXX the meaning of this flag is poorly defined.
1.105 + */
1.106 + const unsigned long LOAD_FLAGS_IS_LINK = 0x0020;
1.107 +
1.108 + /**
1.109 + * This flag specifies that history should not be updated. This flag is only
1.110 + * applicable to loadURI.
1.111 + */
1.112 + const unsigned long LOAD_FLAGS_BYPASS_HISTORY = 0x0040;
1.113 +
1.114 + /**
1.115 + * This flag specifies that any existing history entry should be replaced.
1.116 + * This flag is only applicable to loadURI.
1.117 + */
1.118 + const unsigned long LOAD_FLAGS_REPLACE_HISTORY = 0x0080;
1.119 +
1.120 + /**
1.121 + * This flag specifies that the local web cache should be bypassed, but an
1.122 + * intermediate proxy cache could still be used to satisfy the load.
1.123 + */
1.124 + const unsigned long LOAD_FLAGS_BYPASS_CACHE = 0x0100;
1.125 +
1.126 + /**
1.127 + * This flag specifies that any intermediate proxy caches should be bypassed
1.128 + * (i.e., that the content should be loaded from the origin server).
1.129 + */
1.130 + const unsigned long LOAD_FLAGS_BYPASS_PROXY = 0x0200;
1.131 +
1.132 + /**
1.133 + * This flag specifies that a reload was triggered as a result of detecting
1.134 + * an incorrect character encoding while parsing a previously loaded
1.135 + * document.
1.136 + */
1.137 + const unsigned long LOAD_FLAGS_CHARSET_CHANGE = 0x0400;
1.138 +
1.139 + /**
1.140 + * If this flag is set, Stop() will be called before the load starts
1.141 + * and will stop both content and network activity (the default is to
1.142 + * only stop network activity). Effectively, this passes the
1.143 + * STOP_CONTENT flag to Stop(), in addition to the STOP_NETWORK flag.
1.144 + */
1.145 + const unsigned long LOAD_FLAGS_STOP_CONTENT = 0x0800;
1.146 +
1.147 + /**
1.148 + * A hint this load was prompted by an external program: take care!
1.149 + */
1.150 + const unsigned long LOAD_FLAGS_FROM_EXTERNAL = 0x1000;
1.151 +
1.152 + /**
1.153 + This flag is set when a user explicitly disables the Mixed Content
1.154 + Blocker, and allows Mixed Content to load on an https page.
1.155 + */
1.156 + const unsigned long LOAD_FLAGS_ALLOW_MIXED_CONTENT = 0x2000;
1.157 +
1.158 + /**
1.159 + * This flag specifies that this is the first load in this object.
1.160 + * Set with care, since setting incorrectly can cause us to assume that
1.161 + * nothing was actually loaded in this object if the load ends up being
1.162 + * handled by an external application. This flag must not be passed to
1.163 + * Reload.
1.164 + */
1.165 + const unsigned long LOAD_FLAGS_FIRST_LOAD = 0x4000;
1.166 +
1.167 + /**
1.168 + * This flag specifies that the load should not be subject to popup
1.169 + * blocking checks. This flag must not be passed to Reload.
1.170 + */
1.171 + const unsigned long LOAD_FLAGS_ALLOW_POPUPS = 0x8000;
1.172 +
1.173 + /**
1.174 + * This flag specifies that the URI classifier should not be checked for
1.175 + * this load. This flag must not be passed to Reload.
1.176 + */
1.177 + const unsigned long LOAD_FLAGS_BYPASS_CLASSIFIER = 0x10000;
1.178 +
1.179 + /**
1.180 + * Force relevant cookies to be sent with this load even if normally they
1.181 + * wouldn't be.
1.182 + */
1.183 + const unsigned long LOAD_FLAGS_FORCE_ALLOW_COOKIES = 0x20000;
1.184 +
1.185 + /**
1.186 + * Prevent the owner principal from being inherited for this load.
1.187 + */
1.188 + const unsigned long LOAD_FLAGS_DISALLOW_INHERIT_OWNER = 0x40000;
1.189 +
1.190 + /**
1.191 + * This flag specifies that the URI may be submitted to a third-party
1.192 + * server for correction. This should only be applied to non-sensitive
1.193 + * URIs entered by users. This flag must not be passed to Reload.
1.194 + */
1.195 + const unsigned long LOAD_FLAGS_ALLOW_THIRD_PARTY_FIXUP = 0x100000;
1.196 +
1.197 + /**
1.198 + * This flag specifies that common scheme typos should be corrected.
1.199 + */
1.200 + const unsigned long LOAD_FLAGS_FIXUP_SCHEME_TYPOS = 0x200000;
1.201 +
1.202 + /* Note that flag 0x80000 is available. */
1.203 +
1.204 + /**
1.205 + * Loads a given URI. This will give priority to loading the requested URI
1.206 + * in the object implementing this interface. If it can't be loaded here
1.207 + * however, the URI dispatcher will go through its normal process of content
1.208 + * loading.
1.209 + *
1.210 + * @param aURI
1.211 + * The URI string to load. For HTTP and FTP URLs and possibly others,
1.212 + * characters above U+007F will be converted to UTF-8 and then URL-
1.213 + * escaped per the rules of RFC 2396.
1.214 + * @param aLoadFlags
1.215 + * Flags modifying load behaviour. This parameter is a bitwise
1.216 + * combination of the load flags defined above. (Undefined bits are
1.217 + * reserved for future use.) Generally you will pass LOAD_FLAGS_NONE
1.218 + * for this parameter.
1.219 + * @param aReferrer
1.220 + * The referring URI. If this argument is null, then the referring
1.221 + * URI will be inferred internally.
1.222 + * @param aPostData
1.223 + * If the URI corresponds to a HTTP request, then this stream is
1.224 + * appended directly to the HTTP request headers. It may be prefixed
1.225 + * with additional HTTP headers. This stream must contain a "\r\n"
1.226 + * sequence separating any HTTP headers from the HTTP request body.
1.227 + * This parameter is optional and may be null.
1.228 + * @param aHeaders
1.229 + * If the URI corresponds to a HTTP request, then any HTTP headers
1.230 + * contained in this stream are set on the HTTP request. The HTTP
1.231 + * header stream is formatted as:
1.232 + * ( HEADER "\r\n" )*
1.233 + * This parameter is optional and may be null.
1.234 + */
1.235 + void loadURI(in wstring aURI,
1.236 + in unsigned long aLoadFlags,
1.237 + in nsIURI aReferrer,
1.238 + in nsIInputStream aPostData,
1.239 + in nsIInputStream aHeaders);
1.240 +
1.241 + /**
1.242 + * Loads a given URI. This will give priority to loading the requested URI
1.243 + * in the object implementing this interface. If it can't be loaded here
1.244 + * however, the URI dispatcher will go through its normal process of content
1.245 + * loading.
1.246 + * Behaves like loadURI, except an additional parameter is provided to supply
1.247 + * a base URI to be used in specific situations where one cannot be inferred
1.248 + * by other means, for example when this is called to view selection source.
1.249 + * Outside of these situations, the behaviour of this function is no
1.250 + * different to loadURI.
1.251 + *
1.252 + * @param aURI
1.253 + * The URI string to load. For HTTP and FTP URLs and possibly others,
1.254 + * characters above U+007F will be converted to UTF-8 and then URL-
1.255 + * escaped per the rules of RFC 2396.
1.256 + * @param aLoadFlags
1.257 + * Flags modifying load behaviour. This parameter is a bitwise
1.258 + * combination of the load flags defined above. (Undefined bits are
1.259 + * reserved for future use.) Generally you will pass LOAD_FLAGS_NONE
1.260 + * for this parameter.
1.261 + * @param aReferrer
1.262 + * The referring URI. If this argument is null, then the referring
1.263 + * URI will be inferred internally.
1.264 + * @param aPostData
1.265 + * If the URI corresponds to a HTTP request, then this stream is
1.266 + * appended directly to the HTTP request headers. It may be prefixed
1.267 + * with additional HTTP headers. This stream must contain a "\r\n"
1.268 + * sequence separating any HTTP headers from the HTTP request body.
1.269 + * This parameter is optional and may be null.
1.270 + * @param aHeaders
1.271 + * If the URI corresponds to a HTTP request, then any HTTP headers
1.272 + * contained in this stream are set on the HTTP request. The HTTP
1.273 + * header stream is formatted as:
1.274 + * ( HEADER "\r\n" )*
1.275 + * This parameter is optional and may be null.
1.276 + * @param aBaseURI
1.277 + * Set to indicate a base URI to be associated with the load. Note
1.278 + * that at present this argument is only used with view-source aURIs
1.279 + * and cannot be used to resolve aURI.
1.280 + * This parameter is optional and may be null.
1.281 + */
1.282 + void loadURIWithBase(in wstring aURI,
1.283 + in unsigned long aLoadFlags,
1.284 + in nsIURI aReferrer,
1.285 + in nsIInputStream aPostData,
1.286 + in nsIInputStream aHeaders,
1.287 + in nsIURI aBaseURI);
1.288 +
1.289 + /**
1.290 + * Tells the Object to reload the current page. There may be cases where the
1.291 + * user will be asked to confirm the reload (for example, when it is
1.292 + * determined that the request is non-idempotent).
1.293 + *
1.294 + * @param aReloadFlags
1.295 + * Flags modifying load behaviour. This parameter is a bitwise
1.296 + * combination of the Load Flags defined above. (Undefined bits are
1.297 + * reserved for future use.) Generally you will pass LOAD_FLAGS_NONE
1.298 + * for this parameter.
1.299 + *
1.300 + * @throw NS_BINDING_ABORTED
1.301 + * Indicating that the user canceled the reload.
1.302 + */
1.303 + void reload(in unsigned long aReloadFlags);
1.304 +
1.305 + /****************************************************************************
1.306 + * The following flags may be passed as the stop flags parameter to the stop
1.307 + * method defined on this interface.
1.308 + */
1.309 +
1.310 + /**
1.311 + * This flag specifies that all network activity should be stopped. This
1.312 + * includes both active network loads and pending META-refreshes.
1.313 + */
1.314 + const unsigned long STOP_NETWORK = 0x01;
1.315 +
1.316 + /**
1.317 + * This flag specifies that all content activity should be stopped. This
1.318 + * includes animated images, plugins and pending Javascript timeouts.
1.319 + */
1.320 + const unsigned long STOP_CONTENT = 0x02;
1.321 +
1.322 + /**
1.323 + * This flag specifies that all activity should be stopped.
1.324 + */
1.325 + const unsigned long STOP_ALL = 0x03;
1.326 +
1.327 + /**
1.328 + * Stops a load of a URI.
1.329 + *
1.330 + * @param aStopFlags
1.331 + * This parameter is one of the stop flags defined above.
1.332 + */
1.333 + void stop(in unsigned long aStopFlags);
1.334 +
1.335 + /**
1.336 + * Retrieves the current DOM document for the frame, or lazily creates a
1.337 + * blank document if there is none. This attribute never returns null except
1.338 + * for unexpected error situations.
1.339 + */
1.340 + readonly attribute nsIDOMDocument document;
1.341 +
1.342 + /**
1.343 + * The currently loaded URI or null.
1.344 + */
1.345 + readonly attribute nsIURI currentURI;
1.346 +
1.347 + /**
1.348 + * The referring URI for the currently loaded URI or null.
1.349 + */
1.350 + readonly attribute nsIURI referringURI;
1.351 +
1.352 + /**
1.353 + * The session history object used by this web navigation instance.
1.354 + */
1.355 + attribute nsISHistory sessionHistory;
1.356 +};
