The Tor Browser / file comparison

comparison: uriloader/base/nsIWebProgressListener.idl

uriloader/base/nsIWebProgressListener.idl

changeset 0
6474c204b198
equal deleted inserted replaced
-1:000000000000 0:6e9aafb72254
1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 *
3 * This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6
7 #include "nsISupports.idl"
8
9 interface nsIWebProgress;
10 interface nsIRequest;
11 interface nsIURI;
12
13 /**
14 * The nsIWebProgressListener interface is implemented by clients wishing to
15 * listen in on the progress associated with the loading of asynchronous
16 * requests in the context of a nsIWebProgress instance as well as any child
17 * nsIWebProgress instances. nsIWebProgress.idl describes the parent-child
18 * relationship of nsIWebProgress instances.
19 */
20 [scriptable, uuid(a0cda7e4-c6ca-11e0-b6a5-001320257da5)]
21 interface nsIWebProgressListener : nsISupports
22 {
23 /**
24 * State Transition Flags
25 *
26 * These flags indicate the various states that requests may transition
27 * through as they are being loaded. These flags are mutually exclusive.
28 *
29 * For any given request, onStateChange is called once with the STATE_START
30 * flag, zero or more times with the STATE_TRANSFERRING flag or once with the
31 * STATE_REDIRECTING flag, and then finally once with the STATE_STOP flag.
32 * NOTE: For document requests, a second STATE_STOP is generated (see the
33 * description of STATE_IS_WINDOW for more details).
34 *
35 * STATE_START
36 * This flag indicates the start of a request. This flag is set when a
37 * request is initiated. The request is complete when onStateChange is
38 * called for the same request with the STATE_STOP flag set.
39 *
40 * STATE_REDIRECTING
41 * This flag indicates that a request is being redirected. The request
42 * passed to onStateChange is the request that is being redirected. When a
43 * redirect occurs, a new request is generated automatically to process the
44 * new request. Expect a corresponding STATE_START event for the new
45 * request, and a STATE_STOP for the redirected request.
46 *
47 * STATE_TRANSFERRING
48 * This flag indicates that data for a request is being transferred to an
49 * end consumer. This flag indicates that the request has been targeted,
50 * and that the user may start seeing content corresponding to the request.
51 *
52 * STATE_NEGOTIATING
53 * This flag is not used.
54 *
55 * STATE_STOP
56 * This flag indicates the completion of a request. The aStatus parameter
57 * to onStateChange indicates the final status of the request.
58 */
59 const unsigned long STATE_START = 0x00000001;
60 const unsigned long STATE_REDIRECTING = 0x00000002;
61 const unsigned long STATE_TRANSFERRING = 0x00000004;
62 const unsigned long STATE_NEGOTIATING = 0x00000008;
63 const unsigned long STATE_STOP = 0x00000010;
64
65
66 /**
67 * State Type Flags
68 *
69 * These flags further describe the entity for which the state transition is
70 * occuring. These flags are NOT mutually exclusive (i.e., an onStateChange
71 * event may indicate some combination of these flags).
72 *
73 * STATE_IS_REQUEST
74 * This flag indicates that the state transition is for a request, which
75 * includes but is not limited to document requests. (See below for a
76 * description of document requests.) Other types of requests, such as
77 * requests for inline content (e.g., images and stylesheets) are
78 * considered normal requests.
79 *
80 * STATE_IS_DOCUMENT
81 * This flag indicates that the state transition is for a document request.
82 * This flag is set in addition to STATE_IS_REQUEST. A document request
83 * supports the nsIChannel interface and its loadFlags attribute includes
84 * the nsIChannel::LOAD_DOCUMENT_URI flag.
85 *
86 * A document request does not complete until all requests associated with
87 * the loading of its corresponding document have completed. This includes
88 * other document requests (e.g., corresponding to HTML <iframe> elements).
89 * The document corresponding to a document request is available via the
90 * DOMWindow attribute of onStateChange's aWebProgress parameter.
91 *
92 * STATE_IS_NETWORK
93 * This flag indicates that the state transition corresponds to the start
94 * or stop of activity in the indicated nsIWebProgress instance. This flag
95 * is accompanied by either STATE_START or STATE_STOP, and it may be
96 * combined with other State Type Flags.
97 *
98 * Unlike STATE_IS_WINDOW, this flag is only set when activity within the
99 * nsIWebProgress instance being observed starts or stops. If activity
100 * only occurs in a child nsIWebProgress instance, then this flag will be
101 * set to indicate the start and stop of that activity.
102 *
103 * For example, in the case of navigation within a single frame of a HTML
104 * frameset, a nsIWebProgressListener instance attached to the
105 * nsIWebProgress of the frameset window will receive onStateChange calls
106 * with the STATE_IS_NETWORK flag set to indicate the start and stop of
107 * said navigation. In other words, an observer of an outer window can
108 * determine when activity, that may be constrained to a child window or
109 * set of child windows, starts and stops.
110 *
111 * STATE_IS_WINDOW
112 * This flag indicates that the state transition corresponds to the start
113 * or stop of activity in the indicated nsIWebProgress instance. This flag
114 * is accompanied by either STATE_START or STATE_STOP, and it may be
115 * combined with other State Type Flags.
116 *
117 * This flag is similar to STATE_IS_DOCUMENT. However, when a document
118 * request completes, two onStateChange calls with STATE_STOP are
119 * generated. The document request is passed as aRequest to both calls.
120 * The first has STATE_IS_REQUEST and STATE_IS_DOCUMENT set, and the second
121 * has the STATE_IS_WINDOW flag set (and possibly the STATE_IS_NETWORK flag
122 * set as well -- see above for a description of when the STATE_IS_NETWORK
123 * flag may be set). This second STATE_STOP event may be useful as a way
124 * to partition the work that occurs when a document request completes.
125 */
126 const unsigned long STATE_IS_REQUEST = 0x00010000;
127 const unsigned long STATE_IS_DOCUMENT = 0x00020000;
128 const unsigned long STATE_IS_NETWORK = 0x00040000;
129 const unsigned long STATE_IS_WINDOW = 0x00080000;
130
131
132 /**
133 * State Modifier Flags
134 *
135 * These flags further describe the transition which is occuring. These
136 * flags are NOT mutually exclusive (i.e., an onStateChange event may
137 * indicate some combination of these flags).
138 *
139 * STATE_RESTORING
140 * This flag indicates that the state transition corresponds to the start
141 * or stop of activity for restoring a previously-rendered presentation.
142 * As such, there is no actual network activity associated with this
143 * request, and any modifications made to the document or presentation
144 * when it was originally loaded will still be present.
145 */
146 const unsigned long STATE_RESTORING = 0x01000000;
147
148 /**
149 * State Security Flags
150 *
151 * These flags describe the security state reported by a call to the
152 * onSecurityChange method. These flags are mutually exclusive.
153 *
154 * STATE_IS_INSECURE
155 * This flag indicates that the data corresponding to the request
156 * was received over an insecure channel.
157 *
158 * STATE_IS_BROKEN
159 * This flag indicates an unknown security state. This may mean that the
160 * request is being loaded as part of a page in which some content was
161 * received over an insecure channel.
162 *
163 * STATE_IS_SECURE
164 * This flag indicates that the data corresponding to the request was
165 * received over a secure channel. The degree of security is expressed by
166 * STATE_SECURE_HIGH, STATE_SECURE_MED, or STATE_SECURE_LOW.
167 */
168 const unsigned long STATE_IS_INSECURE = 0x00000004;
169 const unsigned long STATE_IS_BROKEN = 0x00000001;
170 const unsigned long STATE_IS_SECURE = 0x00000002;
171
172 /**
173 * Mixed active content flags
174 *
175 * May be set in addition to the State Security Flags, to indicate that
176 * mixed active content has been encountered.
177 *
178 * STATE_BLOCKED_MIXED_ACTIVE_CONTENT
179 * Mixed active content has been blocked from loading.
180 *
181 * STATE_LOADED_MIXED_ACTIVE_CONTENT
182 * Mixed active content has been loaded. State should be STATE_IS_BROKEN.
183 */
184 const unsigned long STATE_BLOCKED_MIXED_ACTIVE_CONTENT = 0x00000010;
185 const unsigned long STATE_LOADED_MIXED_ACTIVE_CONTENT = 0x00000020;
186
187 /**
188 * Mixed display content flags
189 *
190 * May be set in addition to the State Security Flags, to indicate that
191 * mixed display content has been encountered.
192 *
193 * STATE_BLOCKED_MIXED_DISPLAY_CONTENT
194 * Mixed display content has been blocked from loading.
195 *
196 * STATE_LOADED_MIXED_DISPLAY_CONTENT
197 * Mixed display content has been loaded. State should be STATE_IS_BROKEN.
198 */
199 const unsigned long STATE_BLOCKED_MIXED_DISPLAY_CONTENT = 0x00000100;
200 const unsigned long STATE_LOADED_MIXED_DISPLAY_CONTENT = 0x00000200;
201
202 /**
203 * Security Strength Flags
204 *
205 * These flags describe the security strength and accompany STATE_IS_SECURE
206 * in a call to the onSecurityChange method. These flags are mutually
207 * exclusive.
208 *
209 * These flags are not meant to provide a precise description of data
210 * transfer security. These are instead intended as a rough indicator that
211 * may be used to, for example, color code a security indicator or otherwise
212 * provide basic data transfer security feedback to the user.
213 *
214 * STATE_SECURE_HIGH
215 * This flag indicates a high degree of security.
216 *
217 * STATE_SECURE_MED
218 * This flag indicates a medium degree of security.
219 *
220 * STATE_SECURE_LOW
221 * This flag indicates a low degree of security.
222 */
223 const unsigned long STATE_SECURE_HIGH = 0x00040000;
224 const unsigned long STATE_SECURE_MED = 0x00010000;
225 const unsigned long STATE_SECURE_LOW = 0x00020000;
226
227 /**
228 * State bits for EV == Extended Validation == High Assurance
229 *
230 * These flags describe the level of identity verification
231 * in a call to the onSecurityChange method.
232 *
233 * STATE_IDENTITY_EV_TOPLEVEL
234 * The topmost document uses an EV cert.
235 * NOTE: Available since Gecko 1.9
236 */
237
238 const unsigned long STATE_IDENTITY_EV_TOPLEVEL = 0x00100000;
239
240 /**
241 * Notification indicating the state has changed for one of the requests
242 * associated with aWebProgress.
243 *
244 * @param aWebProgress
245 * The nsIWebProgress instance that fired the notification
246 * @param aRequest
247 * The nsIRequest that has changed state.
248 * @param aStateFlags
249 * Flags indicating the new state. This value is a combination of one
250 * of the State Transition Flags and one or more of the State Type
251 * Flags defined above. Any undefined bits are reserved for future
252 * use.
253 * @param aStatus
254 * Error status code associated with the state change. This parameter
255 * should be ignored unless aStateFlags includes the STATE_STOP bit.
256 * The status code indicates success or failure of the request
257 * associated with the state change. NOTE: aStatus may be a success
258 * code even for server generated errors, such as the HTTP 404 error.
259 * In such cases, the request itself should be queried for extended
260 * error information (e.g., for HTTP requests see nsIHttpChannel).
261 */
262 void onStateChange(in nsIWebProgress aWebProgress,
263 in nsIRequest aRequest,
264 in unsigned long aStateFlags,
265 in nsresult aStatus);
266
267 /**
268 * Notification that the progress has changed for one of the requests
269 * associated with aWebProgress. Progress totals are reset to zero when all
270 * requests in aWebProgress complete (corresponding to onStateChange being
271 * called with aStateFlags including the STATE_STOP and STATE_IS_WINDOW
272 * flags).
273 *
274 * @param aWebProgress
275 * The nsIWebProgress instance that fired the notification.
276 * @param aRequest
277 * The nsIRequest that has new progress.
278 * @param aCurSelfProgress
279 * The current progress for aRequest.
280 * @param aMaxSelfProgress
281 * The maximum progress for aRequest.
282 * @param aCurTotalProgress
283 * The current progress for all requests associated with aWebProgress.
284 * @param aMaxTotalProgress
285 * The total progress for all requests associated with aWebProgress.
286 *
287 * NOTE: If any progress value is unknown, or if its value would exceed the
288 * maximum value of type long, then its value is replaced with -1.
289 *
290 * NOTE: If the object also implements nsIWebProgressListener2 and the caller
291 * knows about that interface, this function will not be called. Instead,
292 * nsIWebProgressListener2::onProgressChange64 will be called.
293 */
294 void onProgressChange(in nsIWebProgress aWebProgress,
295 in nsIRequest aRequest,
296 in long aCurSelfProgress,
297 in long aMaxSelfProgress,
298 in long aCurTotalProgress,
299 in long aMaxTotalProgress);
300
301 /**
302 * Flags for onLocationChange
303 *
304 * LOCATION_CHANGE_SAME_DOCUMENT
305 * This flag is on when |aWebProgress| did not load a new document.
306 * For example, the location change is due to an anchor scroll or a
307 * pushState/popState/replaceState.
308 *
309 * LOCATION_CHANGE_ERROR_PAGE
310 * This flag is on when |aWebProgress| redirected from the requested
311 * contents to an internal page to show error status, such as
312 * <about:neterror>, <about:certerror> and so on.
313 *
314 * Generally speaking, |aURI| and |aRequest| are the original data. DOM
315 * |window.location.href| is also the original location, while
316 * |document.documentURI| is the redirected location. Sometimes |aURI| is
317 * <about:blank> and |aRequest| is null when the original data does not
318 + remain.
319 *
320 * |aWebProgress| does NOT set this flag when it did not try to load a new
321 * document. In this case, it should set LOCATION_CHANGE_SAME_DOCUMENT.
322 */
323 const unsigned long LOCATION_CHANGE_SAME_DOCUMENT = 0x00000001;
324 const unsigned long LOCATION_CHANGE_ERROR_PAGE = 0x00000002;
325
326 /**
327 * Called when the location of the window being watched changes. This is not
328 * when a load is requested, but rather once it is verified that the load is
329 * going to occur in the given window. For instance, a load that starts in a
330 * window might send progress and status messages for the new site, but it
331 * will not send the onLocationChange until we are sure that we are loading
332 * this new page here.
333 *
334 * @param aWebProgress
335 * The nsIWebProgress instance that fired the notification.
336 * @param aRequest
337 * The associated nsIRequest. This may be null in some cases.
338 * @param aLocation
339 * The URI of the location that is being loaded.
340 * @param aFlags
341 * This is a value which explains the situation or the reason why
342 * the location has changed.
343 */
344 void onLocationChange(in nsIWebProgress aWebProgress,
345 in nsIRequest aRequest,
346 in nsIURI aLocation,
347 [optional] in unsigned long aFlags);
348
349 /**
350 * Notification that the status of a request has changed. The status message
351 * is intended to be displayed to the user (e.g., in the status bar of the
352 * browser).
353 *
354 * @param aWebProgress
355 * The nsIWebProgress instance that fired the notification.
356 * @param aRequest
357 * The nsIRequest that has new status.
358 * @param aStatus
359 * This value is not an error code. Instead, it is a numeric value
360 * that indicates the current status of the request. This interface
361 * does not define the set of possible status codes. NOTE: Some
362 * status values are defined by nsITransport and nsISocketTransport.
363 * @param aMessage
364 * Localized text corresponding to aStatus.
365 */
366 void onStatusChange(in nsIWebProgress aWebProgress,
367 in nsIRequest aRequest,
368 in nsresult aStatus,
369 in wstring aMessage);
370
371 /**
372 * Notification called for security progress. This method will be called on
373 * security transitions (eg HTTP -> HTTPS, HTTPS -> HTTP, FOO -> HTTPS) and
374 * after document load completion. It might also be called if an error
375 * occurs during network loading.
376 *
377 * @param aWebProgress
378 * The nsIWebProgress instance that fired the notification.
379 * @param aRequest
380 * The nsIRequest that has new security state.
381 * @param aState
382 * A value composed of the Security State Flags and the Security
383 * Strength Flags listed above. Any undefined bits are reserved for
384 * future use.
385 *
386 * NOTE: These notifications will only occur if a security package is
387 * installed.
388 */
389 void onSecurityChange(in nsIWebProgress aWebProgress,
390 in nsIRequest aRequest,
391 in unsigned long aState);
392 };

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial