netwerk/base/public/nsIChannelEventSink.idl@6474c204b198
netwerk/base/public/nsIChannelEventSink.idl
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /* vim:set ts=4 sw=4 sts=4 cin: */
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/. */
7 #include "nsISupports.idl"
9 interface nsIChannel;
10 interface nsIAsyncVerifyRedirectCallback;
12 /**
13 * Implement this interface to receive control over various channel events.
14 * Channels will try to get this interface from a channel's
15 * notificationCallbacks or, if not available there, from the loadGroup's
16 * notificationCallbacks.
17 *
18 * These methods are called before onStartRequest.
19 */
20 [scriptable, uuid(a430d870-df77-4502-9570-d46a8de33154)]
21 interface nsIChannelEventSink : nsISupports
22 {
23 /**
24 * This is a temporary redirect. New requests for this resource should
25 * continue to use the URI of the old channel.
26 *
27 * The new URI may be identical to the old one.
28 */
29 const unsigned long REDIRECT_TEMPORARY = 1 << 0;
31 /**
32 * This is a permanent redirect. New requests for this resource should use
33 * the URI of the new channel (This might be an HTTP 301 reponse).
34 * If this flag is not set, this is a temporary redirect.
35 *
36 * The new URI may be identical to the old one.
37 */
38 const unsigned long REDIRECT_PERMANENT = 1 << 1;
40 /**
41 * This is an internal redirect, i.e. it was not initiated by the remote
42 * server, but is specific to the channel implementation.
43 *
44 * The new URI may be identical to the old one.
45 */
46 const unsigned long REDIRECT_INTERNAL = 1 << 2;
48 /**
49 * Called when a redirect occurs. This may happen due to an HTTP 3xx status
50 * code. The purpose of this method is to notify the sink that a redirect
51 * is about to happen, but also to give the sink the right to veto the
52 * redirect by throwing or passing a failure-code in the callback.
53 *
54 * Note that vetoing the redirect simply means that |newChannel| will not
55 * be opened. It is important to understand that |oldChannel| will continue
56 * loading as if it received a HTTP 200, which includes notifying observers
57 * and possibly display or process content attached to the HTTP response.
58 * If the sink wants to prevent this loading it must explicitly deal with
59 * it, e.g. by calling |oldChannel->Cancel()|
60 *
61 * There is a certain freedom in implementing this method:
62 *
63 * If the return-value indicates success, a callback on |callback| is
64 * required. This callback can be done from within asyncOnChannelRedirect
65 * (effectively making the call synchronous) or at some point later
66 * (making the call asynchronous). Repeat: A callback must be done
67 * if this method returns successfully.
68 *
69 * If the return value indicates error (method throws an exception)
70 * the redirect is vetoed and no callback must be done. Repeat: No
71 * callback must be done if this method throws!
72 *
73 * @see nsIAsyncVerifyRedirectCallback::onRedirectVerifyCallback()
74 *
75 * @param oldChannel
76 * The channel that's being redirected.
77 * @param newChannel
78 * The new channel. This channel is not opened yet.
79 * @param flags
80 * Flags indicating the type of redirect. A bitmask consisting
81 * of flags from above.
82 * One of REDIRECT_TEMPORARY and REDIRECT_PERMANENT will always be
83 * set.
84 * @param callback
85 * Object to inform about the async result of this method
86 *
87 * @throw <any> Throwing an exception will cause the redirect to be
88 * cancelled
89 */
90 void asyncOnChannelRedirect(in nsIChannel oldChannel,
91 in nsIChannel newChannel,
92 in unsigned long flags,
93 in nsIAsyncVerifyRedirectCallback callback);
94 };
