1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/uriloader/base/nsIWebProgressListener.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,392 @@
1.4 +/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.5 + *
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +
1.12 +interface nsIWebProgress;
1.13 +interface nsIRequest;
1.14 +interface nsIURI;
1.15 +
1.16 +/**
1.17 + * The nsIWebProgressListener interface is implemented by clients wishing to
1.18 + * listen in on the progress associated with the loading of asynchronous
1.19 + * requests in the context of a nsIWebProgress instance as well as any child
1.20 + * nsIWebProgress instances. nsIWebProgress.idl describes the parent-child
1.21 + * relationship of nsIWebProgress instances.
1.22 + */
1.23 +[scriptable, uuid(a0cda7e4-c6ca-11e0-b6a5-001320257da5)]
1.24 +interface nsIWebProgressListener : nsISupports
1.25 +{
1.26 + /**
1.27 + * State Transition Flags
1.28 + *
1.29 + * These flags indicate the various states that requests may transition
1.30 + * through as they are being loaded. These flags are mutually exclusive.
1.31 + *
1.32 + * For any given request, onStateChange is called once with the STATE_START
1.33 + * flag, zero or more times with the STATE_TRANSFERRING flag or once with the
1.34 + * STATE_REDIRECTING flag, and then finally once with the STATE_STOP flag.
1.35 + * NOTE: For document requests, a second STATE_STOP is generated (see the
1.36 + * description of STATE_IS_WINDOW for more details).
1.37 + *
1.38 + * STATE_START
1.39 + * This flag indicates the start of a request. This flag is set when a
1.40 + * request is initiated. The request is complete when onStateChange is
1.41 + * called for the same request with the STATE_STOP flag set.
1.42 + *
1.43 + * STATE_REDIRECTING
1.44 + * This flag indicates that a request is being redirected. The request
1.45 + * passed to onStateChange is the request that is being redirected. When a
1.46 + * redirect occurs, a new request is generated automatically to process the
1.47 + * new request. Expect a corresponding STATE_START event for the new
1.48 + * request, and a STATE_STOP for the redirected request.
1.49 + *
1.50 + * STATE_TRANSFERRING
1.51 + * This flag indicates that data for a request is being transferred to an
1.52 + * end consumer. This flag indicates that the request has been targeted,
1.53 + * and that the user may start seeing content corresponding to the request.
1.54 + *
1.55 + * STATE_NEGOTIATING
1.56 + * This flag is not used.
1.57 + *
1.58 + * STATE_STOP
1.59 + * This flag indicates the completion of a request. The aStatus parameter
1.60 + * to onStateChange indicates the final status of the request.
1.61 + */
1.62 + const unsigned long STATE_START = 0x00000001;
1.63 + const unsigned long STATE_REDIRECTING = 0x00000002;
1.64 + const unsigned long STATE_TRANSFERRING = 0x00000004;
1.65 + const unsigned long STATE_NEGOTIATING = 0x00000008;
1.66 + const unsigned long STATE_STOP = 0x00000010;
1.67 +
1.68 +
1.69 + /**
1.70 + * State Type Flags
1.71 + *
1.72 + * These flags further describe the entity for which the state transition is
1.73 + * occuring. These flags are NOT mutually exclusive (i.e., an onStateChange
1.74 + * event may indicate some combination of these flags).
1.75 + *
1.76 + * STATE_IS_REQUEST
1.77 + * This flag indicates that the state transition is for a request, which
1.78 + * includes but is not limited to document requests. (See below for a
1.79 + * description of document requests.) Other types of requests, such as
1.80 + * requests for inline content (e.g., images and stylesheets) are
1.81 + * considered normal requests.
1.82 + *
1.83 + * STATE_IS_DOCUMENT
1.84 + * This flag indicates that the state transition is for a document request.
1.85 + * This flag is set in addition to STATE_IS_REQUEST. A document request
1.86 + * supports the nsIChannel interface and its loadFlags attribute includes
1.87 + * the nsIChannel::LOAD_DOCUMENT_URI flag.
1.88 + *
1.89 + * A document request does not complete until all requests associated with
1.90 + * the loading of its corresponding document have completed. This includes
1.91 + * other document requests (e.g., corresponding to HTML <iframe> elements).
1.92 + * The document corresponding to a document request is available via the
1.93 + * DOMWindow attribute of onStateChange's aWebProgress parameter.
1.94 + *
1.95 + * STATE_IS_NETWORK
1.96 + * This flag indicates that the state transition corresponds to the start
1.97 + * or stop of activity in the indicated nsIWebProgress instance. This flag
1.98 + * is accompanied by either STATE_START or STATE_STOP, and it may be
1.99 + * combined with other State Type Flags.
1.100 + *
1.101 + * Unlike STATE_IS_WINDOW, this flag is only set when activity within the
1.102 + * nsIWebProgress instance being observed starts or stops. If activity
1.103 + * only occurs in a child nsIWebProgress instance, then this flag will be
1.104 + * set to indicate the start and stop of that activity.
1.105 + *
1.106 + * For example, in the case of navigation within a single frame of a HTML
1.107 + * frameset, a nsIWebProgressListener instance attached to the
1.108 + * nsIWebProgress of the frameset window will receive onStateChange calls
1.109 + * with the STATE_IS_NETWORK flag set to indicate the start and stop of
1.110 + * said navigation. In other words, an observer of an outer window can
1.111 + * determine when activity, that may be constrained to a child window or
1.112 + * set of child windows, starts and stops.
1.113 + *
1.114 + * STATE_IS_WINDOW
1.115 + * This flag indicates that the state transition corresponds to the start
1.116 + * or stop of activity in the indicated nsIWebProgress instance. This flag
1.117 + * is accompanied by either STATE_START or STATE_STOP, and it may be
1.118 + * combined with other State Type Flags.
1.119 + *
1.120 + * This flag is similar to STATE_IS_DOCUMENT. However, when a document
1.121 + * request completes, two onStateChange calls with STATE_STOP are
1.122 + * generated. The document request is passed as aRequest to both calls.
1.123 + * The first has STATE_IS_REQUEST and STATE_IS_DOCUMENT set, and the second
1.124 + * has the STATE_IS_WINDOW flag set (and possibly the STATE_IS_NETWORK flag
1.125 + * set as well -- see above for a description of when the STATE_IS_NETWORK
1.126 + * flag may be set). This second STATE_STOP event may be useful as a way
1.127 + * to partition the work that occurs when a document request completes.
1.128 + */
1.129 + const unsigned long STATE_IS_REQUEST = 0x00010000;
1.130 + const unsigned long STATE_IS_DOCUMENT = 0x00020000;
1.131 + const unsigned long STATE_IS_NETWORK = 0x00040000;
1.132 + const unsigned long STATE_IS_WINDOW = 0x00080000;
1.133 +
1.134 +
1.135 + /**
1.136 + * State Modifier Flags
1.137 + *
1.138 + * These flags further describe the transition which is occuring. These
1.139 + * flags are NOT mutually exclusive (i.e., an onStateChange event may
1.140 + * indicate some combination of these flags).
1.141 + *
1.142 + * STATE_RESTORING
1.143 + * This flag indicates that the state transition corresponds to the start
1.144 + * or stop of activity for restoring a previously-rendered presentation.
1.145 + * As such, there is no actual network activity associated with this
1.146 + * request, and any modifications made to the document or presentation
1.147 + * when it was originally loaded will still be present.
1.148 + */
1.149 + const unsigned long STATE_RESTORING = 0x01000000;
1.150 +
1.151 + /**
1.152 + * State Security Flags
1.153 + *
1.154 + * These flags describe the security state reported by a call to the
1.155 + * onSecurityChange method. These flags are mutually exclusive.
1.156 + *
1.157 + * STATE_IS_INSECURE
1.158 + * This flag indicates that the data corresponding to the request
1.159 + * was received over an insecure channel.
1.160 + *
1.161 + * STATE_IS_BROKEN
1.162 + * This flag indicates an unknown security state. This may mean that the
1.163 + * request is being loaded as part of a page in which some content was
1.164 + * received over an insecure channel.
1.165 + *
1.166 + * STATE_IS_SECURE
1.167 + * This flag indicates that the data corresponding to the request was
1.168 + * received over a secure channel. The degree of security is expressed by
1.169 + * STATE_SECURE_HIGH, STATE_SECURE_MED, or STATE_SECURE_LOW.
1.170 + */
1.171 + const unsigned long STATE_IS_INSECURE = 0x00000004;
1.172 + const unsigned long STATE_IS_BROKEN = 0x00000001;
1.173 + const unsigned long STATE_IS_SECURE = 0x00000002;
1.174 +
1.175 + /**
1.176 + * Mixed active content flags
1.177 + *
1.178 + * May be set in addition to the State Security Flags, to indicate that
1.179 + * mixed active content has been encountered.
1.180 + *
1.181 + * STATE_BLOCKED_MIXED_ACTIVE_CONTENT
1.182 + * Mixed active content has been blocked from loading.
1.183 + *
1.184 + * STATE_LOADED_MIXED_ACTIVE_CONTENT
1.185 + * Mixed active content has been loaded. State should be STATE_IS_BROKEN.
1.186 + */
1.187 + const unsigned long STATE_BLOCKED_MIXED_ACTIVE_CONTENT = 0x00000010;
1.188 + const unsigned long STATE_LOADED_MIXED_ACTIVE_CONTENT = 0x00000020;
1.189 +
1.190 + /**
1.191 + * Mixed display content flags
1.192 + *
1.193 + * May be set in addition to the State Security Flags, to indicate that
1.194 + * mixed display content has been encountered.
1.195 + *
1.196 + * STATE_BLOCKED_MIXED_DISPLAY_CONTENT
1.197 + * Mixed display content has been blocked from loading.
1.198 + *
1.199 + * STATE_LOADED_MIXED_DISPLAY_CONTENT
1.200 + * Mixed display content has been loaded. State should be STATE_IS_BROKEN.
1.201 + */
1.202 + const unsigned long STATE_BLOCKED_MIXED_DISPLAY_CONTENT = 0x00000100;
1.203 + const unsigned long STATE_LOADED_MIXED_DISPLAY_CONTENT = 0x00000200;
1.204 +
1.205 + /**
1.206 + * Security Strength Flags
1.207 + *
1.208 + * These flags describe the security strength and accompany STATE_IS_SECURE
1.209 + * in a call to the onSecurityChange method. These flags are mutually
1.210 + * exclusive.
1.211 + *
1.212 + * These flags are not meant to provide a precise description of data
1.213 + * transfer security. These are instead intended as a rough indicator that
1.214 + * may be used to, for example, color code a security indicator or otherwise
1.215 + * provide basic data transfer security feedback to the user.
1.216 + *
1.217 + * STATE_SECURE_HIGH
1.218 + * This flag indicates a high degree of security.
1.219 + *
1.220 + * STATE_SECURE_MED
1.221 + * This flag indicates a medium degree of security.
1.222 + *
1.223 + * STATE_SECURE_LOW
1.224 + * This flag indicates a low degree of security.
1.225 + */
1.226 + const unsigned long STATE_SECURE_HIGH = 0x00040000;
1.227 + const unsigned long STATE_SECURE_MED = 0x00010000;
1.228 + const unsigned long STATE_SECURE_LOW = 0x00020000;
1.229 +
1.230 + /**
1.231 + * State bits for EV == Extended Validation == High Assurance
1.232 + *
1.233 + * These flags describe the level of identity verification
1.234 + * in a call to the onSecurityChange method.
1.235 + *
1.236 + * STATE_IDENTITY_EV_TOPLEVEL
1.237 + * The topmost document uses an EV cert.
1.238 + * NOTE: Available since Gecko 1.9
1.239 + */
1.240 +
1.241 + const unsigned long STATE_IDENTITY_EV_TOPLEVEL = 0x00100000;
1.242 +
1.243 + /**
1.244 + * Notification indicating the state has changed for one of the requests
1.245 + * associated with aWebProgress.
1.246 + *
1.247 + * @param aWebProgress
1.248 + * The nsIWebProgress instance that fired the notification
1.249 + * @param aRequest
1.250 + * The nsIRequest that has changed state.
1.251 + * @param aStateFlags
1.252 + * Flags indicating the new state. This value is a combination of one
1.253 + * of the State Transition Flags and one or more of the State Type
1.254 + * Flags defined above. Any undefined bits are reserved for future
1.255 + * use.
1.256 + * @param aStatus
1.257 + * Error status code associated with the state change. This parameter
1.258 + * should be ignored unless aStateFlags includes the STATE_STOP bit.
1.259 + * The status code indicates success or failure of the request
1.260 + * associated with the state change. NOTE: aStatus may be a success
1.261 + * code even for server generated errors, such as the HTTP 404 error.
1.262 + * In such cases, the request itself should be queried for extended
1.263 + * error information (e.g., for HTTP requests see nsIHttpChannel).
1.264 + */
1.265 + void onStateChange(in nsIWebProgress aWebProgress,
1.266 + in nsIRequest aRequest,
1.267 + in unsigned long aStateFlags,
1.268 + in nsresult aStatus);
1.269 +
1.270 + /**
1.271 + * Notification that the progress has changed for one of the requests
1.272 + * associated with aWebProgress. Progress totals are reset to zero when all
1.273 + * requests in aWebProgress complete (corresponding to onStateChange being
1.274 + * called with aStateFlags including the STATE_STOP and STATE_IS_WINDOW
1.275 + * flags).
1.276 + *
1.277 + * @param aWebProgress
1.278 + * The nsIWebProgress instance that fired the notification.
1.279 + * @param aRequest
1.280 + * The nsIRequest that has new progress.
1.281 + * @param aCurSelfProgress
1.282 + * The current progress for aRequest.
1.283 + * @param aMaxSelfProgress
1.284 + * The maximum progress for aRequest.
1.285 + * @param aCurTotalProgress
1.286 + * The current progress for all requests associated with aWebProgress.
1.287 + * @param aMaxTotalProgress
1.288 + * The total progress for all requests associated with aWebProgress.
1.289 + *
1.290 + * NOTE: If any progress value is unknown, or if its value would exceed the
1.291 + * maximum value of type long, then its value is replaced with -1.
1.292 + *
1.293 + * NOTE: If the object also implements nsIWebProgressListener2 and the caller
1.294 + * knows about that interface, this function will not be called. Instead,
1.295 + * nsIWebProgressListener2::onProgressChange64 will be called.
1.296 + */
1.297 + void onProgressChange(in nsIWebProgress aWebProgress,
1.298 + in nsIRequest aRequest,
1.299 + in long aCurSelfProgress,
1.300 + in long aMaxSelfProgress,
1.301 + in long aCurTotalProgress,
1.302 + in long aMaxTotalProgress);
1.303 +
1.304 + /**
1.305 + * Flags for onLocationChange
1.306 + *
1.307 + * LOCATION_CHANGE_SAME_DOCUMENT
1.308 + * This flag is on when |aWebProgress| did not load a new document.
1.309 + * For example, the location change is due to an anchor scroll or a
1.310 + * pushState/popState/replaceState.
1.311 + *
1.312 + * LOCATION_CHANGE_ERROR_PAGE
1.313 + * This flag is on when |aWebProgress| redirected from the requested
1.314 + * contents to an internal page to show error status, such as
1.315 + * <about:neterror>, <about:certerror> and so on.
1.316 + *
1.317 + * Generally speaking, |aURI| and |aRequest| are the original data. DOM
1.318 + * |window.location.href| is also the original location, while
1.319 + * |document.documentURI| is the redirected location. Sometimes |aURI| is
1.320 + * <about:blank> and |aRequest| is null when the original data does not
1.321 + + remain.
1.322 + *
1.323 + * |aWebProgress| does NOT set this flag when it did not try to load a new
1.324 + * document. In this case, it should set LOCATION_CHANGE_SAME_DOCUMENT.
1.325 + */
1.326 + const unsigned long LOCATION_CHANGE_SAME_DOCUMENT = 0x00000001;
1.327 + const unsigned long LOCATION_CHANGE_ERROR_PAGE = 0x00000002;
1.328 +
1.329 + /**
1.330 + * Called when the location of the window being watched changes. This is not
1.331 + * when a load is requested, but rather once it is verified that the load is
1.332 + * going to occur in the given window. For instance, a load that starts in a
1.333 + * window might send progress and status messages for the new site, but it
1.334 + * will not send the onLocationChange until we are sure that we are loading
1.335 + * this new page here.
1.336 + *
1.337 + * @param aWebProgress
1.338 + * The nsIWebProgress instance that fired the notification.
1.339 + * @param aRequest
1.340 + * The associated nsIRequest. This may be null in some cases.
1.341 + * @param aLocation
1.342 + * The URI of the location that is being loaded.
1.343 + * @param aFlags
1.344 + * This is a value which explains the situation or the reason why
1.345 + * the location has changed.
1.346 + */
1.347 + void onLocationChange(in nsIWebProgress aWebProgress,
1.348 + in nsIRequest aRequest,
1.349 + in nsIURI aLocation,
1.350 + [optional] in unsigned long aFlags);
1.351 +
1.352 + /**
1.353 + * Notification that the status of a request has changed. The status message
1.354 + * is intended to be displayed to the user (e.g., in the status bar of the
1.355 + * browser).
1.356 + *
1.357 + * @param aWebProgress
1.358 + * The nsIWebProgress instance that fired the notification.
1.359 + * @param aRequest
1.360 + * The nsIRequest that has new status.
1.361 + * @param aStatus
1.362 + * This value is not an error code. Instead, it is a numeric value
1.363 + * that indicates the current status of the request. This interface
1.364 + * does not define the set of possible status codes. NOTE: Some
1.365 + * status values are defined by nsITransport and nsISocketTransport.
1.366 + * @param aMessage
1.367 + * Localized text corresponding to aStatus.
1.368 + */
1.369 + void onStatusChange(in nsIWebProgress aWebProgress,
1.370 + in nsIRequest aRequest,
1.371 + in nsresult aStatus,
1.372 + in wstring aMessage);
1.373 +
1.374 + /**
1.375 + * Notification called for security progress. This method will be called on
1.376 + * security transitions (eg HTTP -> HTTPS, HTTPS -> HTTP, FOO -> HTTPS) and
1.377 + * after document load completion. It might also be called if an error
1.378 + * occurs during network loading.
1.379 + *
1.380 + * @param aWebProgress
1.381 + * The nsIWebProgress instance that fired the notification.
1.382 + * @param aRequest
1.383 + * The nsIRequest that has new security state.
1.384 + * @param aState
1.385 + * A value composed of the Security State Flags and the Security
1.386 + * Strength Flags listed above. Any undefined bits are reserved for
1.387 + * future use.
1.388 + *
1.389 + * NOTE: These notifications will only occur if a security package is
1.390 + * installed.
1.391 + */
1.392 + void onSecurityChange(in nsIWebProgress aWebProgress,
1.393 + in nsIRequest aRequest,
1.394 + in unsigned long aState);
1.395 +};
